Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
import { execFile } from 'node:child_process';
import { access, readFile, readdir } from 'node:fs/promises';
import { homedir } from 'node:os';
import { join } from 'node:path';
import { setTimeout as delay } from 'node:timers/promises';
import { promisify } from 'node:util';
import {
deleteSession as sdkDeleteSession,
forkSession as sdkForkSession,
getSessionInfo as sdkGetSessionInfo,
listSessions as sdkListSessions,
type SDKSessionInfo,
type SessionStore,
type SessionStoreEntry,
tagSession as sdkTagSession,
} from '@anthropic-ai/claude-agent-sdk';
import { z } from 'zod';
/** The Claude Code conversations started in a folder outside Switch, newest first. */
export const cliConversationListSchema = z.object({
/**
* Whether every running Claude Code process said which conversation it has
* open. False when this Claude Code keeps no such records, or a live
* process's record could not be read: an open conversation can then look
* like a closed one.
*/
ownershipKnown: z.boolean(),
conversations: z.array(
z.object({
nativeSessionId: z.string(),
title: z.string(),
lastActivityAt: z.number(),
gitBranch: z.string().nullable(),
/** The running Claude Code process that has the conversation open, or null for none. */
openIn: z.object({ pid: z.number(), entrypoint: z.string().nullable() }).nullable(),
})
),
});
export type CliConversationList = z.infer<typeof cliConversationListSchema>;
export const forkedCliConversationSchema = z.object({ nativeSessionId: z.string() });
/** How many copies `--delete-cli-conversation-copies` removed, for each Console session it named. */
export const deletedCliConversationCopiesSchema = z.object({
deleted: z.record(z.string(), z.number().int().min(0)),
});
/** What a fork is titled in Claude Code's own `/resume` list, so it reads as taken. */
const FORK_TITLE_SUFFIX = ' (continued in Switch Console)';
/**
* How every copy Switch makes is tagged: with this and the id of the Console
* session that owns it. The tag is what a copy left by a session that never
* started is found and removed by, and it survives a rename where the title
* would not.
*/
const COPY_TAG_PREFIX = 'switch-console:';
/** The tag of the copy a Console session continues. */
export function cliConversationCopyTag(consoleSessionId: string): string {
return `${COPY_TAG_PREFIX}${consoleSessionId}`;
}
/**
* Whether a conversation is a copy Switch made to continue another, by its
* tag or, for a copy made before copies were tagged, its title.
*/
function isSwitchCopy(session: Pick<SDKSessionInfo, 'tag' | 'summary'>): boolean {
return (
session.tag?.startsWith(COPY_TAG_PREFIX) === true || session.summary.endsWith(FORK_TITLE_SUFFIX)
);
}
/**
* One running Claude Code process's own record, `sessions/<pid>.json` under its
* config directory. Only the conversation it names is required; the rest is
* read where it is in a shape this knows.
*/
const holderRecordSchema = z.object({
sessionId: z.string().min(1),
procStart: z.unknown().optional(),
entrypoint: z.unknown().optional(),
});
/**
* A command line that runs Claude Code: its `claude` executable, or the npm or
* SDK package's script. Not any mention of the word, which a shell running a
* script about `~/.claude` would make.
*/
const CLAUDE_COMMAND =
/(?:^|[/\\\s])claude(?:\.exe)?(?:\s|$)|@anthropic-ai\/claude-(?:code|agent-sdk)\//;
/** How far apart a record's start time and its process's may be and still be the same process. */
const START_TOLERANCE_MS = 5_000;
type Holder = { pid: number; entrypoint: string | null };
type HolderRecord = z.infer<typeof holderRecordSchema>;
/** A running process as `ps` describes it. */
export type ProcessInfo = { startedAt: number | null; command: string };
export interface CliConversationDeps {
listSessions: typeof sdkListSessions;
getSessionInfo: typeof sdkGetSessionInfo;
forkSession: typeof sdkForkSession;
tagSession: typeof sdkTagSession;
deleteSession: typeof sdkDeleteSession;
processExists: (pid: number) => boolean;
/** What `ps` says about these processes, in one call; null when it cannot be asked. */
processes: (pids: number[]) => Promise<Map<number, ProcessInfo> | null>;
}
const defaultDeps: CliConversationDeps = {
listSessions: sdkListSessions,
getSessionInfo: sdkGetSessionInfo,
forkSession: sdkForkSession,
tagSession: sdkTagSession,
deleteSession: sdkDeleteSession,
processExists,
processes,
};
/**
* The conversations started in `dir` from Claude Code's own terminal or IDE
* clients, with the process that has each one open. Conversations a program
* started through the SDK, Switch's own sessions among them, are left out, and
* so are the copies Switch made to continue, renamed or not: one whose session
* went away, or whose copy finished after Console stopped waiting, is not a
* CLI conversation.
*
* `env` is the session's execution environment, so the conversations are
* looked for in the config directory the session's Claude Code will use.
*/
export async function listClaudeCliConversations(
dir: string,
env: Record<string, string | undefined>,
deps: CliConversationDeps = defaultDeps
): Promise<CliConversationList> {
const [sessions, ownership] = await Promise.all([
withClaudeConfigDir(env, () =>
deps.listSessions({ dir, includeProgrammatic: false, includeWorktrees: false })
),
claudeHolders(claudeConfigDir(env), deps),
]);
return {
ownershipKnown: ownership !== null && ownership.complete,
conversations: sessions
.filter((session) => !isSwitchCopy(session))
.sort((a, b) => b.lastModified - a.lastModified)
.map((session) => ({
nativeSessionId: session.sessionId,
title: session.summary,
lastActivityAt: session.lastModified,
gitBranch: session.gitBranch ?? null,
openIn: ownership?.holders.get(session.sessionId) ?? null,
})),
};
}
/**
* A copy of a Claude Code conversation under a new id, for a Switch session to
* continue: the original stays the terminal's, and nothing Switch does is
* written to it. Refused while a running Claude Code process has it open, so
* the copy is never taken from the middle of a turn; and, where Claude Code
* cannot say which conversations are open, unless the person said this one
* is closed (`confirmedClosed`). A copy Switch made is not copied again.
*
* The copy is tagged with the Console session that owns it
* ({@link cliConversationCopyTag}), so one whose session never started can be
* found and removed ({@link deleteClaudeCliConversationCopies}). A copy that
* cannot be tagged is removed at once, since nothing could find it later.
*/
export async function forkClaudeCliConversation(
request: {
dir: string;
nativeSessionId: string;
consoleSessionId: string;
confirmedClosed: boolean;
},
env: Record<string, string | undefined>,
deps: CliConversationDeps = defaultDeps
): Promise<{ nativeSessionId: string }> {
const { dir, nativeSessionId } = request;
const ownership = await claudeHolders(claudeConfigDir(env), deps);
const holder = ownership?.holders.get(nativeSessionId);
if (holder)
throw new Error(
`This conversation is open in Claude Code (process ${holder.pid}). Close it there, then try again.`
);
if (!request.confirmedClosed) {
if (ownership === null)
throw new Error(
'Console cannot tell whether this conversation is open in Claude Code right now. Choose it again and confirm it is closed.'
);
if (!ownership.complete)
throw new Error(
'Console could not read which conversations Claude Code has open right now. Try again in a moment.'
);
}
return withClaudeConfigDir(env, async () => {
const source = await deps.getSessionInfo(nativeSessionId, { dir });
if (!source)
throw new Error(`Claude Code has no conversation ${nativeSessionId} in ${dir} to continue.`);
if (isSwitchCopy(source))
throw new Error(
'This conversation is a copy Switch Console made to continue another one. Choose the conversation it was copied from.'
);
const fork = await deps.forkSession(nativeSessionId, {
dir,
// Cut by code point, so a character outside the BMP is never split in two.
title: `${Array.from(source.summary).slice(0, 200).join('')}${FORK_TITLE_SUFFIX}`,
});
try {
await deps.tagSession(fork.sessionId, cliConversationCopyTag(request.consoleSessionId), {
dir,
});
} catch (error) {
try {
await deps.deleteSession(fork.sessionId, { dir });
} catch (removal) {
throw new Error(
`Could not mark the copy ${fork.sessionId} of this conversation as Switch Console's (${String(error)}), nor remove it (${String(removal)}).`,
{ cause: error }
);
}
throw new Error(
`Could not mark the copy of this conversation as Switch Console's, so it was removed: ${String(error)}`,
{ cause: error }
);
}
return { nativeSessionId: fork.sessionId };
});
}
/**
* Removes the copies in `dir` tagged as any of the given Console sessions',
* and says how many each had: what is left when a session's copy was made but
* the session never started. Only a conversation carrying exactly one of those
* sessions' tags is removed. The folder is listed once for all of them.
*/
export async function deleteClaudeCliConversationCopies(
dir: string,
consoleSessionIds: string[],
env: Record<string, string | undefined>,
deps: CliConversationDeps = defaultDeps
): Promise<{ deleted: Record<string, number> }> {
const owners = new Map(consoleSessionIds.map((id) => [cliConversationCopyTag(id), id]));
return withClaudeConfigDir(env, async () => {
const deleted: Record<string, number> = Object.fromEntries(
consoleSessionIds.map((id) => [id, 0])
);
const sessions = await deps.listSessions({
dir,
includeProgrammatic: true,
includeWorktrees: false,
});
for (const session of sessions) {
const owner = session.tag === undefined ? undefined : owners.get(session.tag);
if (owner === undefined) continue;
await deps.deleteSession(session.sessionId, { dir });
deleted[owner] = (deleted[owner] ?? 0) + 1;
}
return { deleted };
});
}
/**
* The saved conversations under one Claude Code config directory, as the SDK's
* readers take a store: for reading a conversation from the directory a
* session uses without changing this process's environment, which a host
* running other work cannot afford. Read only; a conversation is found by its
* id under any project, as Claude Code's own resume finds it.
*
* Only a last line that is not JSON is left out: a write Claude Code has not
* finished. Anywhere else such a line is a transcript this cannot read whole,
* and reading it is refused rather than shown with a gap.
*/
export function configDirSessionStore(configDir: string): SessionStore {
return {
append: async () => {
throw new Error('This store only reads saved conversations.');
},
load: async ({ sessionId, subpath }) => {
if (subpath !== undefined) return null;
const path = await savedConversationPath(configDir, sessionId);
if (path === null) return null;
const lines = (await readFile(path, 'utf8')).split('\n');
let last = lines.length - 1;
while (last >= 0 && !lines[last]!.trim()) last--;
return lines.flatMap((line, index): SessionStoreEntry[] => {
if (!line.trim()) return [];
try {
return [JSON.parse(line) as SessionStoreEntry];
} catch (error) {
if (index === last) return [];
throw new Error(
`Line ${index + 1} of Claude Code's saved conversation ${path} is not JSON: ${String(error)}`,
{ cause: error }
);
}
});
},
};
}
/**
* Where Claude Code saved the conversation with this id under a config
* directory, `projects/<directory>/<id>.jsonl` in whichever project it was
* started in; null when it saved none.
*/
export async function savedConversationPath(
configDir: string,
sessionId: string
): Promise<string | null> {
const projects = join(configDir, 'projects');
let names: string[];
try {
names = await readdir(projects);
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
throw error;
}
for (const name of names) {
const path = join(projects, name, `${sessionId}.jsonl`);
try {
await access(path);
return path;
} catch (error) {
const code = (error as NodeJS.ErrnoException).code;
if (code !== 'ENOENT' && code !== 'ENOTDIR') throw error;
}
}
return null;
}
/** Where Claude Code keeps its conversations for a process with this environment. */
export function claudeConfigDir(env: Record<string, string | undefined>): string {
return env.CLAUDE_CONFIG_DIR || join(env.HOME || homedir(), '.claude');
}
/** The last `withClaudeConfigDir` call to settle; each waits for the one before. */
let configDirTurn: Promise<unknown> = Promise.resolve();
/**
* Runs `work` with this process's `CLAUDE_CONFIG_DIR` naming the directory
* `env` gives Claude Code. Listing and copying use the SDK's own file access,
* which takes the directory from this process's environment and remembers it
* per value of the variable, so setting it is enough. For the host's one-off
* commands, each its own short-lived process; a long-lived host reads through
* {@link configDirSessionStore} instead. Calls take turns all the same, and
* are not to be nested: an inner call would wait for the outer one for ever.
*/
export function withClaudeConfigDir<T>(
env: Record<string, string | undefined>,
work: () => Promise<T>
): Promise<T> {
const run = configDirTurn.then(async () => {
const previous = process.env.CLAUDE_CONFIG_DIR;
process.env.CLAUDE_CONFIG_DIR = claudeConfigDir(env);
try {
return await work();
} finally {
if (previous === undefined) delete process.env.CLAUDE_CONFIG_DIR;
else process.env.CLAUDE_CONFIG_DIR = previous;
}
});
configDirTurn = run.catch(() => {});
return run;
}
/**
* The conversations Claude Code's running processes have open, by
* conversation id, from the record each process keeps. Null when there are no
* records at all: a Claude Code too old to keep them.
*
* Wrong in the safe direction where it has to be. A record whose process has
* gone holds nothing, and neither does one whose process id now names
* something other than Claude Code that started at another time. A live
* process that is Claude Code holds its conversation whatever its start time
* says, since a clock that was stepped moves that; so does one `ps` cannot
* describe. A live process whose record cannot be read leaves `complete` false.
*/
async function claudeHolders(
dir: string,
deps: CliConversationDeps
): Promise<{ holders: Map<string, Holder>; complete: boolean } | null> {
let names: string[];
try {
names = await readdir(join(dir, 'sessions'));
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
throw error;
}
const records: { pid: number; record: HolderRecord | null }[] = [];
for (const name of names) {
const pid = Number(/^(\d+)\.json$/.exec(name)?.[1]);
if (!Number.isSafeInteger(pid) || pid <= 0 || !deps.processExists(pid)) continue;
const record = await readHolderRecord(join(dir, 'sessions', name));
if (record !== 'gone') records.push({ pid, record });
}
const described = records.length ? await deps.processes(records.map((r) => r.pid)) : null;
const holders = new Map<string, Holder>();
let complete = true;
for (const { pid, record } of records) {
const info = described?.get(pid);
if (info && !CLAUDE_COMMAND.test(info.command)) {
const recorded = recordedStart(record?.procStart);
if (
recorded === null ||
info.startedAt === null ||
Math.abs(info.startedAt - recorded) > START_TOLERANCE_MS
)
continue;
}
if (!record) {
complete = false;
continue;
}
holders.set(record.sessionId, {
pid,
entrypoint: typeof record.entrypoint === 'string' ? record.entrypoint : null,
});
}
return { holders, complete };
}
/**
* A process record, read twice before giving up: its process rewrites it each
* time it goes busy or idle, so one read can meet it half written. Null when it
* cannot be read; `gone` when its process removed it, which it does on exit.
*/
async function readHolderRecord(path: string): Promise<HolderRecord | null | 'gone'> {
for (let attempt = 0; ; attempt++) {
try {
return holderRecordSchema.parse(JSON.parse(await readFile(path, 'utf8')));
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'gone';
if (attempt > 0) {
console.warn(`Could not read Claude Code's process record ${path}: ${String(error)}`);
return null;
}
await delay(100);
}
}
}
/** A record's `procStart`, which Claude Code writes as `ps -o lstart=` prints it in UTC. */
function recordedStart(value: unknown): number | null {
if (typeof value !== 'string') return null;
const parsed = Date.parse(`${value.trim()} UTC`);
return Number.isNaN(parsed) ? null : parsed;
}
function processExists(pid: number): boolean {
try {
process.kill(pid, 0);
return true;
} catch (error) {
// EPERM: it exists, as another user's.
return (error as NodeJS.ErrnoException).code !== 'ESRCH';
}
}
/**
* `ps -o pid=,lstart=,args=` for these processes, in UTC and the C locale so its
* start time reads as Claude Code's records write it. A process that has gone
* is not in the answer; `ps` then exits 1 if none is left.
*/
async function processes(pids: number[]): Promise<Map<number, ProcessInfo> | null> {
if (process.platform === 'win32') return null;
let stdout: string;
try {
({ stdout } = await promisify(execFile)(
'ps',
['-o', 'pid=,lstart=,args=', '-p', pids.join(',')],
{ encoding: 'utf8', env: { ...process.env, TZ: 'UTC', LC_ALL: 'C' } }
));
} catch (error) {
const output = (error as { stdout?: unknown }).stdout;
if ((error as { code?: unknown }).code !== 1 || typeof output !== 'string') {
console.warn(
`Could not ask ps about Claude Code's processes, so each live one is taken to hold its conversation: ${String(error)}`
);
return null;
}
stdout = output;
}
const described = new Map<number, ProcessInfo>();
for (const line of stdout.split('\n')) {
const [pid, weekday, month, day, time, year, ...command] = line.trim().split(/\s+/);
if (!pid || !year) continue;
const startedAt = Date.parse(`${weekday} ${month} ${day} ${time} ${year} UTC`);
described.set(Number(pid), {
startedAt: Number.isNaN(startedAt) ? null : startedAt,
command: command.join(' '),
});
}
return described;
}