Chats Router

Create and manage chat sessions, workspaces, and sub-chats in 1Code Desktop

Overview

The Chats router manages chat sessions (workspaces) and sub-chats. Each chat represents a workspace with an optional git worktree, and can contain multiple sub-chats (conversation threads).

Chat Structure

• Chat (Workspace): Top-level container with optional git worktree isolation
• Sub-Chat: Individual conversation thread within a chat
• Messages: Array of user and assistant messages within a sub-chat

Chat Methods

list

List all non-archived chats, optionally filtered by project.

const chats = await trpc.chats.list.query({
  projectId: 'proj_123' // optional
});

projectId · string

Filter chats by project ID

Returns: Chat[] (ordered by most recently updated)

---

listArchived

List archived chats.

const archived = await trpc.chats.listArchived.query({
  projectId: 'proj_123' // optional
});

projectId · string

Filter by project ID

Returns: Chat[] (ordered by archive date)

---

get

Get a single chat with all sub-chats and project info.

const chat = await trpc.chats.get.query({ id: 'chat_123' });

if (chat) {
  console.log('Chat:', chat.name);
  console.log('Sub-chats:', chat.subChats.length);
  console.log('Project:', chat.project?.name);
}

id · string · required

Chat ID

Returns: ChatWithSubChatsAndProject | null

---

create

Create a new chat with optional git worktree.

const chat = await trpc.chats.create.mutate({
  projectId: 'proj_123',
  name: 'Fix authentication bug',
  initialMessage: 'Help me fix the login flow',
  useWorktree: true,
  baseBranch: 'main',
  mode: 'agent'
});

projectId · string · required

Project ID

name · string

Chat name (auto-generated if not provided)

initialMessage · string

First user message

initialMessageParts · array

Message parts (for images or file content)

model · string

AI model to use

baseBranch · string

Base branch for worktree (default: main)

branchType · enum · default: "local"

local or remote

useWorktree · boolean · default: true

Create isolated git worktree

mode · enum · default: "agent"

agent or plan

Returns: Chat & { subChats: SubChat[] }

---

rename

Rename a chat.

const chat = await trpc.chats.rename.mutate({
  id: 'chat_123',
  name: 'Authentication fixes'
});

id · string · required

Chat ID

name · string · required

New name (min 1 character)

---

archive

Archive a chat and optionally delete its worktree.

const chat = await trpc.chats.archive.mutate({
  id: 'chat_123',
  deleteWorktree: true
});

id · string · required

Chat ID

deleteWorktree · boolean · default: false

Delete the git worktree to free disk space

Archiving also kills any terminal processes in the workspace.

---

restore

Restore an archived chat.

const chat = await trpc.chats.restore.mutate({ id: 'chat_123' });

---

delete

Permanently delete a chat with worktree cleanup.

const deleted = await trpc.chats.delete.mutate({ id: 'chat_123' });

This permanently deletes the chat, all sub-chats, and the git worktree. This action cannot be undone.

---

archiveBatch

Archive multiple chats at once.

const archived = await trpc.chats.archiveBatch.mutate({
  chatIds: ['chat_123', 'chat_456', 'chat_789']
});

Sub-Chat Methods

getSubChat

Get a single sub-chat with its parent chat and project.

const subChat = await trpc.chats.getSubChat.query({ id: 'sub_123' });

---

createSubChat

Create a new sub-chat (conversation thread).

const subChat = await trpc.chats.createSubChat.mutate({
  chatId: 'chat_123',
  name: 'Add tests',
  mode: 'agent'
});

chatId · string · required

Parent chat ID

name · string

Sub-chat name

mode · enum · default: "agent"

agent or plan

---

forkSubChat

Fork a sub-chat from a specific message, preserving SDK session context.

const result = await trpc.chats.forkSubChat.mutate({
  subChatId: 'sub_123',
  messageId: 'msg_456',
  name: 'Alternative approach' // optional
});

console.log('Forked sub-chat:', result.subChat.id);
console.log('Forked', result.messageCount, 'messages');

subChatId · string · required

Source sub-chat ID

messageId · string · required

Message ID to fork from

messageIndex · number

Fallback message index (0-based)

name · string

Custom name for forked sub-chat

Returns:

{
  subChat: SubChat;
  messageCount: number;
  forkAtSdkUuid: string | null;
}

---

updateSubChatMessages

Update the messages array for a sub-chat.

const subChat = await trpc.chats.updateSubChatMessages.mutate({
  id: 'sub_123',
  messages: JSON.stringify(messagesArray)
});

---

rollbackToMessage

Rollback to a specific message, reverting both git state and message history.

const result = await trpc.chats.rollbackToMessage.mutate({
  subChatId: 'sub_123',
  sdkMessageUuid: 'uuid_456'
});

if (result.success) {
  console.log('Rolled back to', result.messages.length, 'messages');
} else {
  console.error('Rollback failed:', result.error);
}

subChatId · string · required

Sub-chat ID

sdkMessageUuid · string · required

SDK message UUID to rollback to

Returns:

| { success: true; messages: any[] }
| { success: false; error: string }

---

updateSubChatSession

Update the session ID for Claude resume.

const subChat = await trpc.chats.updateSubChatSession.mutate({
  id: 'sub_123',
  sessionId: 'session_abc'
});

---

updateSubChatMode

Switch between plan and agent mode.

const subChat = await trpc.chats.updateSubChatMode.mutate({
  id: 'sub_123',
  mode: 'plan'
});

---

renameSubChat

Rename a sub-chat.

const subChat = await trpc.chats.renameSubChat.mutate({
  id: 'sub_123',
  name: 'New name'
});

---

deleteSubChat

Delete a sub-chat.

const deleted = await trpc.chats.deleteSubChat.mutate({ id: 'sub_123' });

Git Methods

getDiff

Get the git diff for a chat’s worktree.

const result = await trpc.chats.getDiff.query({ chatId: 'chat_123' });

if (result.diff) {
  console.log('Diff:', result.diff);
} else {
  console.error('Error:', result.error);
}

Returns: { diff: string | null; error?: string }

---

getParsedDiff

Get parsed diff with prefetched file contents.

const result = await trpc.chats.getParsedDiff.query({ chatId: 'chat_123' });

console.log('Files changed:', result.files.length);
console.log('Lines added:', result.totalAdditions);
console.log('Lines deleted:', result.totalDeletions);

for (const file of result.files) {
  console.log(`${file.oldPath} -> ${file.newPath}`);
  console.log(`  +${file.additions} -${file.deletions}`);
}

Returns:

{
  files: ParsedFile[];
  totalAdditions: number;
  totalDeletions: number;
  fileContents: Record<string, string>;
  error?: string;
}

---

generateCommitMessage

Generate an AI commit message based on diff.

const result = await trpc.chats.generateCommitMessage.mutate({
  chatId: 'chat_123',
  filePaths: ['src/auth.ts', 'src/user.ts'], // optional
  ollamaModel: 'llama3.2' // optional, for offline mode
});

console.log('Commit message:', result.message);

chatId · string · required

Chat ID

filePaths · string[]

Only generate message for these files

ollamaModel · string

Ollama model for offline generation

---

generateSubChatName

Generate an AI name for a sub-chat.

const result = await trpc.chats.generateSubChatName.mutate({
  userMessage: 'Fix the authentication bug in the login flow',
  ollamaModel: 'llama3.2' // optional
});

console.log('Generated name:', result.name);

PR Methods

getPrContext

Get PR context for message generation.

const context = await trpc.chats.getPrContext.query({ chatId: 'chat_123' });

if (context) {
  console.log('Branch:', context.branch);
  console.log('Base:', context.baseBranch);
  console.log('Uncommitted:', context.uncommittedCount);
  console.log('Has upstream:', context.hasUpstream);
}

---

updatePrInfo

Update PR info after creating a PR.

const chat = await trpc.chats.updatePrInfo.mutate({
  chatId: 'chat_123',
  prUrl: 'https://github.com/owner/repo/pull/42',
  prNumber: 42
});

---

getPrStatus

Get PR status from GitHub.

const status = await trpc.chats.getPrStatus.query({ chatId: 'chat_123' });

if (status?.pr) {
  console.log('State:', status.pr.state);
  console.log('Mergeable:', status.pr.mergeable);
}

---

mergePr

Merge a PR via gh CLI.

try {
  await trpc.chats.mergePr.mutate({
    chatId: 'chat_123',
    method: 'squash' // 'merge', 'squash', or 'rebase'
  });
  console.log('PR merged successfully');
} catch (error) {
  if (error.message.includes('MERGE_CONFLICT')) {
    console.error('PR has conflicts');
  }
}

File Stats

getFileStats

Get file change statistics for workspaces.

const stats = await trpc.chats.getFileStats.query({
  openSubChatIds: ['sub_123', 'sub_456']
});

for (const stat of stats) {
  console.log(`${stat.chatId}: ${stat.editCount} edits, ${stat.writeCount} writes`);
}