Terminal-native agent for real codebases

A coding agent that learns your project before it changes it.

Topchester builds a local map of your repo first, then uses it while planning, editing, checking work, and keeping project knowledge current.

Install Topchester View source
topchester / terminal agent

Quickstart

Install, configure, sync, run.

Start with the npm package, add a small model config, build the project knowledge base, then open the terminal agent.

npm install -g topchester-ai
2. Set key export OPENROUTER_API_KEY=...
3. Sync knowledge 
topchester kb init
topchester kb sync
4. Start topchester

Config

Add one small config file.

Create topchester.jsonc in the project Topchester should work on. Keep API keys in environment variables, not committed files.

Minimal 
{
  "$schema": "https://topchester.com/schemas/config.v1.json",
  "models": {
    "default": "openrouter/google/gemini-3.1-flash-lite"
  }
}
Stronger chat model 
{
  "$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"
  }
}
01

Project knowledge first

Topchester builds and syncs a repo-local topchester-kb/ so the agent starts from a project map instead of rediscovering everything from raw files.

02

Drift-aware workflow

It shows when project knowledge is stale and lets you sync changed files back into the KB.

03

Terminal-native TUI

Chat, inspect tool output, review diffs, resume sessions, and keep working from the terminal without switching into a heavyweight IDE workflow.

Features

Built for real repository work.

Topchester combines a repo knowledge base with the practical tools expected from a coding agent: file edits, tests, Git, sessions, and safe command execution.

KB-first context

Sync a local project map before work starts, then keep it current as files change.

Drift-aware sync

Use kb status, kb sync, and kb sync --full to keep knowledge fresh.

Terminal-native TUI

Chat, review tool output, follow progress, and resume work without leaving the terminal.

Precise file tools

Read, search, create, and edit workspace files with hash-aware safeguards around writes.

Tests and checks

Run test, lint, typecheck, build, format-check, and smoke commands through a strict validator path.

Git workflow

Inspect status, diffs, and logs, then stage or commit only explicitly acknowledged files.

Task planning

Keep a visible session plan for multi-step changes without burying the thread in checklist prose.

Subagents and sessions

Delegate focused exploration, persist session logs, and resume the latest project-local conversation.

Model flexibility

Use one model for everything, or route chat and KB summaries to different configured models.

Local by default

Store project knowledge, caches, logs, and sessions in predictable repo-local folders.

Workflow

Sync knowledge, then code with context.

  1. Run Topchester in a project directory.
  2. Initialize and sync the project knowledge base.
  3. Ask the agent to plan, edit, test, and keep the KB fresh.