Topchester
Changelog Docs

CLI commands

Common commands:

topchester
topchester info
topchester --resume latest
topchester fork --last
topchester fork 019e9029-0000-7000-8000-000000000001
topchester run "Edit greeting.txt and change Hello to Goodbye."
topchester run /kb status
topchester run "/skill code-review review this diff"
topchester search "status bar"
topchester auth login codex --device
topchester auth status
topchester mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
topchester mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github

topchester kb init
topchester kb sync
topchester kb status
topchester kb search "post author update error"
topchester kb context "status bar" --json
topchester kb sync --full
topchester kb reset

Global options

  • -c, --config <path> uses an explicit config file.
  • --workspace <path> uses this workspace root. Defaults to the current working directory.
  • --resume <session> resumes a project-local session from .agents/topchester/sessions/. Use latest or an exact lowercase session ID.
  • --dev <flag> enables a development-only UI or runtime flag. Can be repeated.
  • -V, --version prints the CLI package version.
  • -h, --help prints help.

Command overview

Command Purpose
topchester Start the interactive coding agent.
topchester auth Manage global provider authentication.
topchester fork Fork a saved project-local session and open the fork.
topchester info Show config validity and local runtime hints.
topchester mcp add Add or replace a stdio MCP server in config.
topchester run Run one prompt or slash command without opening the TUI.
topchester search Search compiled L1 file knowledge.
topchester kb init Create the project knowledge folders.
topchester kb context Create an L1 context pack for a query.
topchester kb dry-run Preview which files would be synced.
topchester kb search Search compiled L1 file knowledge.
topchester kb sync Build or update L1 entries for non-clean files.
topchester kb reset Delete the local knowledge base and cache.
topchester kb status Show files that are not current in the knowledge base.
topchester update Update Topchester with npm, pnpm, or bun.

topchester info

topchester info is a lite doctor command. It does not open the TUI, contact model providers, start MCP servers, or create project state folders.

Reports config layers, whether the effective config is valid, configured model/provider hints, provider API key env presence, MCP server command presence, hook counts, and local session/log/knowledge paths.

If config is invalid, it prints the config error and exits nonzero.

topchester auth login codex --device

Starts the SSH-friendly Codex ChatGPT device login flow. Topchester prints a verification URL, one-time user code, expiry time, and phishing warning. Open the URL in any browser, enter the code, and return to the terminal while Topchester polls for approval.

On success, Topchester stores OAuth tokens in ~/.config/topchester/auth.json, configures the global codex provider in ~/.config/topchester/config.jsonc, and seeds starter Codex model choices. Token values are not printed.

topchester auth --help and topchester auth login --help list supported auth providers and examples. Bare topchester auth login, unsupported providers, and topchester auth login codex without --device print the codex provider, exact login command, and next help command instead of only reporting a missing argument.

topchester auth status

Shows the global auth store path and redacted provider auth state. It reports whether stored access and refresh tokens exist, whether a provider needs refresh or relogin, and never prints token values.

topchester mcp add

Adds or replaces a stdio MCP server entry:

topchester mcp add <server-name> --env KEY=VALUE -- <stdio server-command> [args...]

--env KEY=VALUE can be repeated. Server names use letters, numbers, -, and _. The command writes to --config when provided, otherwise to ~/.config/topchester/config.jsonc.

topchester fork

topchester fork --last forks the newest project-local session. topchester fork <session-id> forks that exact project-local session. Bare topchester fork exits with a clear message until Topchester has a fork-specific saved-session picker.

The fork gets a fresh top-level session ID, opens through the normal resume hydration path, and records source-session lineage in metadata. The source session log is left untouched. Child task session folders are not copied in V0.

topchester run

Runs one prompt or slash command without opening the TUI.

topchester run "Read data.txt and summarize it."
topchester run --json "Edit greeting.txt and change Hello to Goodbye."
topchester run --output-json /tmp/topchester-events.jsonl "Run /kb status"
topchester run --dangerously-auto-approve --json "Run the benchmark task."
topchester run --dangerously-auto-approve --benchmark-profile terminal-bench --json "Run the Terminal-Bench task."
topchester run /kb status

Options:

  • --model <model> overrides the agent.primary model for this run.
  • --timeout <ms> stops the run after this many milliseconds.
  • --json writes JSONL run events to stdout.
  • --output-json <path> writes JSONL run events to a file.
  • --dangerously-auto-approve auto-approves prompt-gated tool calls for this non-interactive run.
  • --benchmark-profile <profile> enables an explicit benchmark runtime profile. The supported profile is terminal-bench.

--dangerously-auto-approve is intended for benchmarks and automation that cannot answer approval prompts. It only bypasses prompts that would otherwise ask the user, currently approval-required bash calls. Hard policy rejects, deny rules, destructive command detection, workspace boundary failures, profile/tool-catalog denial, and hook block or stop responses still apply. Auto-approved bash commands are approved only for the current tool execution and are not written to topchester.jsonc.

--benchmark-profile terminal-bench is for disposable Terminal-Bench containers. It keeps configured bash deny rules, but allows broad shell commands through the bash tool so tasks can create files, run services, build archives, configure local system state, or perform other terminal work inside the benchmark sandbox. It also lets successful workspace-changing bash calls satisfy the non-interactive finish gate for non-code tasks.

Run JSON includes a per-run runId, dangerouslyAutoApprove and benchmarkProfile in the run.started event, and permission_auto_approved runtime events when a permission prompt is bypassed.

The agent can use web_fetch during topchester and topchester run sessions to read public HTTP(S) pages, including docs, changelogs, API references, issue pages, and package notes. web_fetch returns markdown by default, can return plain text or HTML, blocks localhost and private-network addresses, strips credentials from URLs, and stops at cross-host redirects so the next URL is visible as a separate tool call. Raw responses over 5 MB fail, and returned text is capped at 40,000 characters with a [truncated] marker. The tool is available to the primary agent and general subagents, but not the read-only explore subagent.