Documentation

Quickstart

Get up and running in under a minute.

cd my-project
toporic

Installation

Toporic is distributed as a single static binary. The only runtime dependency is rg (ripgrep) for the search_files tool.

macOS / Linux

chmod +x toporic
sudo cp toporic /usr/local/bin/
# Or user-local
mkdir -p ~/.local/bin && cp toporic ~/.local/bin/
toporic --help

Windows

The TUI requires a terminal that supports raw mode — use Windows Terminal or WSL.

Setting API keys

Two options — config file (recommended) or environment variables:

# Option A — Save to config (recommended)
toporic set-key --provider anthropic --key sk-ant-...
toporic set-key --provider openai --key sk-...

# Option B — Environment variable (takes priority)
export ANTHROPIC_API_KEY="sk-ant-..."

Supported Providers

21+ LLM providers are supported out of the box. Choose one with --provider or set it in config.

Ollama (local models)

No API key needed. Run Ollama alongside Toporic:

ollama serve &
toporic --provider ollama --model llama3

Default endpoint: http://localhost:11434. Override via providers.ollama.base_url in config.

CLI Reference

toporic                                         # Coding mode (default)
toporic --mode assistant                        # Conversational
toporic --mode research                         # Web research
toporic --provider openai --model gpt-4o-mini   # Different backend
toporic --resume                                # Resume latest session
toporic --no-persist                            # Don't save session

All flags

Subcommands

Override priority

CLI flags → config file → built-in defaults. Environment variables override config file API keys.

Agent Modes

Three modes for different workflows. Switch with --mode flag, config, or Ctrl+, overlay.

TUI Reference

Layout

The TUI has five zones:

1. Title bar — app name, mode badge, spinner, token gauge, cost, git branch
2. Sidebar — toggle with Ctrl+B (≥100 columns, appears to the right). Shows tasks, modified files
3. Chat area — messages, reasoning blocks, collapsible tool calls
4. Input box — multiline entry (up to 5 visible lines)
5. Footer — keyboard hints, workspace path, git branch

Tool calls

Tool calls appear as collapsible units: ▸ command_name ✓ (green) or ✗ (red). Press Enter or Space in message focus to expand and see full arguments and results.

Confirm dialog

Before mutating tools (run_command, write_file, etc.), a confirmation popup appears. Y to accept, N / Enter / Esc to reject.

Command palette

Press Ctrl+P for a fuzzy-searchable list of actions: change provider, model, theme, language, start new session, and more.

Auto-scroll

Enabled by default. Pause with PageUp, resume with End. The [END] indicator shows when active.

Keybindings

Sessions

Every interaction is saved automatically under ~/.toporic/sessions/. Sessions persist across restarts and can be resumed with --resume.

toporic --resum                                    # Latest session
toporic --resume 550e8400-e29b-41d4-a716-446655440000  # By UUID
toporic --no-persist                                # No disk write
# Start a fresh session from within the TUI
/session new

Tools Reference

20+ tools across seven categories. All sandboxed to the Git workspace root.

Configuration

Config file: ~/.toporic/config.json

{
  "defaults": {
    "mode": "coding",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "theme": "amber",
    "language": "English",
    "models": { "anthropic": "...", "openai": "gpt-4o" }
  },
  "providers": {
    "anthropic": "sk-ant-...",
    "openai": "sk-...",
    "ollama": { "base_url": "http://localhost:11434", "model": "llama3" }
  },
  "provider_urls": { "deepseek": "http://localhost:7897" },
  "embedding": { "provider": "voyage" }
}

CLI flags override config values. Environment variables override API keys. Changes via Ctrl+P command palette are saved to config automatically.

Skills

Skills are reusable instruction bundles (Markdown with YAML frontmatter) that give the agent project-specific context. The agent sees a compact index of all skills every turn.

Discovery paths (priority order)

1. {workspace_root}/.toporic/skills/ — project-local
2. ~/.toporic/skills/ — user-wide
3. /etc/toporic/skills/ — system-wide

Using skills

Invoke a skill explicitly from the TUI input:

Workspace Initialization

Run /init in the TUI to bootstrap a project workspace. Creates .toporic/skills/ and AGENTS.md. Runs git init if needed. Idempotent — safe to run multiple times.

.toporic/
└── skills/       ← project-local skills
AGENTS.md         ← project instructions (read every turn)

Use AGENTS.md to give the agent project-specific instructions, conventions, and context — it's read on every turn.

Troubleshooting

Terminal too small

Requires ≥20 columns × 6 rows. Resize and the TUI re-renders on next keystroke.

Shift+Enter not inserting newline

Use Alt+Enter as an alternative.

Ollama not responding

Verify curl http://localhost:11434 and ensure the model is pulled: ollama pull llama3.

Rate limit errors (429)

Auto-retries with exponential backoff (500ms → 1s → 2s, up to 3 attempts). Respects Retry-After header.

Debug logging

RUST_LOG=debug toporic
tail -f ~/.toporic/toporic.log

Context limit warning

Footer shows ⚠ Context at 91% — consider /session new. Start a new session or let the agent compact automatically.