Topchester Agent

Website: https://topchester.com

Topchester is a terminal coding agent that learns a project before it starts making changes. It builds a local project knowledge base, uses that knowledge while chatting and editing, and helps keep the knowledge current as the code changes.

If you have used tools like Codex, Claude Code, or OpenCode, the shape should feel familiar: install a CLI, cd into a repo, run a command, chat in your terminal, review changes, and keep working. The difference is that Topchester treats project knowledge as part of the agent, not as an optional side index.

Quick Start

Requirements:

• Node.js >=18 and npm for installation. The installed Topchester runtime is a standalone executable and does not require Bun.
• macOS on Apple Silicon, or glibc Linux on ARM64 or x64. Intel macOS, Windows, and musl Linux are not supported by the standalone release.
• A model provider key. The example below uses OpenRouter.

Install the CLI:

npm install -g topchester-ai

Set your API key:

export OPENROUTER_API_KEY=...

Start the agent with a model reference:

topchester -m openrouter/google/gemini-3.1-flash-lite

No model config is needed for this command. Topchester recognizes the built-in OpenRouter provider and keeps the selection in the session without editing JSONC. Inside the TUI, initialize and build the project knowledge base:

/kb init
/kb sync

For the short setup guide, see onboarding.md.

What Topchester Creates

Topchester keeps project knowledge and local runtime data in separate places:

• topchester-kb/ — compiled project knowledge. This is the canonical knowledge base for the repo.
• .agents/topchester-kb-cache/ — local generated cache and queue files.
• .agents/topchester/sessions/ — local chat sessions, metadata, and event logs.
• .agents/topchester/logs/ — local debug logs when logging is enabled.

Session folders, caches, and logs are local machine state and should not be committed.

Everyday Commands

topchester
topchester -m openrouter/google/gemini-3.1-flash-lite
topchester --resume latest
topchester run -m openrouter/google/gemini-3.1-flash-lite "Summarize this project."

topchester kb status
topchester kb sync
topchester kb sync --full
topchester kb search "status bar"
topchester kb reset

Useful TUI slash commands:

/kb status
/kb sync
/kb sync --full
/skills
/new

topchester kb status is the cheap check. It shows files that are not current in the knowledge base. topchester kb sync builds the KB when it is empty and updates only non-clean files afterward. Use topchester kb sync --full to rebuild every in-scope file and remove orphaned L1 entries.

Configuration

Use -m provider/model for a one-session chat selection. Add --kb-model provider/model when you want a different model for knowledge-base summaries without writing config:

topchester -m openrouter/anthropic/claude-sonnet-4.5 \
  --kb-model openrouter/google/gemini-3.1-flash-lite

Add JSONC when you want durable defaults, shared project policy, or custom providers.

The smallest config uses one OpenRouter model for all Topchester work:

{
  "$schema": "https://topchester.com/schemas/config.v1.json",
  "models": {
    "default": "openrouter/google/gemini-3.1-flash-lite",
  },
}

You can also use a stronger model for chat and a cheaper model for KB summaries:

{
  "$schema": "https://topchester.com/schemas/config.v1.json",
  "models": {
    "default": "openrouter/anthropic/claude-sonnet-4.5",
    "kb.summarize": "openrouter/google/gemini-3.1-flash-lite",
  },
}

Do not commit API keys. Put keys in environment variables, a user config file, or an uncommitted local config.

Topchester reads workspace config, user config, and one optional selected profile in this order:

1. topchester.jsonc
2. ~/.config/topchester/config.jsonc
3. --config <path> when supplied, otherwise TOPCHESTER_CONFIG

--config and TOPCHESTER_CONFIG are two ways to select the same profile slot. If both are set, --config wins and the environment-selected file is not merged.

On first startup, Topchester creates ~/.config/topchester/config.jsonc with a commented minimal example. Uncomment it to set your personal default model, or keep shared project policy in topchester.jsonc.

How The Knowledge Base Works

topchester kb sync scans the workspace, respects .gitignore, skips generated/cache folders, and writes L1 knowledge entries under topchester-kb/l1-files/.

The compiler uses models["kb.summarize"] when it is configured. If it is not configured, it uses models.default.

Common KB states:

• kb: ready — the KB exists and has compiled content.
• kb: empty — the KB folder exists but has no compiled content yet.
• kb: missing — run topchester kb init, then topchester kb sync.
• N dirty — run topchester kb sync.

Working From Source

This section is for contributors working in this repository.

mise install
pnpm install
mise run build
mise exec -- bun dist/bin.mjs --help

Common repo checks:

mise run local-ci
mise run check
mise run test
mise run package-check
mise run opentui-pty-smoke

The repository pins Bun, Node, and pnpm through mise. Bun builds and runs the CLI from source; published npm installs run the compiled standalone executable.

The package name is topchester-ai; the installed command is topchester.

Read More

• Onboarding
• Docs
• Quickstart
• CLI Commands
• TUI
• Skills
• Configuration
• Models and providers
• Knowledge base
• Sessions