Commands

8gent provides two entry points: the full command 8gent and the short alias 8.

Launch the TUI

# Full command (after npm install -g @8gi-foundation/8gent-code)
8gent

# Short alias
8

# From source (contributors)
bun run tui

Specify a Provider

8gent --provider <name> switches the active provider. Run 8gent providers to list available names.

# Switch to OpenRouter cloud models. Default active provider is "8gent"
# (local localhost:11434, model eight-1.0-q3:14b), with "ollama" also enabled.
8gent --provider openrouter

Auth Commands

8gent includes Clerk-based authentication for syncing sessions and preferences. Auth is optional. The agent works fully offline without logging in.

# Log in via device code flow
8gent auth login

# Log out
8gent auth logout

# Check current auth status
8gent auth status

# Show current user info
8gent auth whoami

Tokens are stored in the macOS Keychain when available, with an AES-256-GCM encrypted file fallback on other platforms.

AST Commands

Query code structure without reading entire files:

# Show file outline (all symbols with signatures)
8gent outline src/parser.ts

# Get a specific symbol's source
8gent symbol src/parser.ts::buildSymbolId

Benchmark Commands

# Run the full benchmark suite
bun run benchmark:v2

# Run autoresearch loop
CATEGORY=battle-test MAX_ITERATIONS=5 bun run benchmark:loop

# Overnight runner
bash benchmarks/autoresearch/overnight-runner.sh

# Validate a kernel fine-tuning checkpoint
bun run benchmarks/autoresearch/validate-checkpoint.ts

Code Review

# Review the current git diff
8gent review

# Review a specific GitHub PR
8gent review --pr <n>

The agent loads the diff, evaluates correctness and style, and returns inline findings. --pr <n> fetches the PR from GitHub and posts review comments directly.

Export

8gent export <session-id>

Exports a session as a self-contained HTML file for sharing or archival. Find session IDs with harness sessions.

Infinite Mode

8gent infinite <task>

Runs the agent autonomously without per-step prompts until the task is complete or a stop condition triggers. Use for long-running background tasks. The agent loops on its own plan, executing and verifying until done. Resource usage scales with task complexity - set a time or token budget with --budget-tokens <n> or --budget-minutes <n>.

Server Modes

# Expose 8gent as an MCP server
8gent mcp-server

# Run as a JSON-RPC server for programmatic control
8gent rpc

mcp-server lets MCP-aware clients (Claude Desktop, IDEs, other agents) consume 8gent's tools over the Model Context Protocol. Configure the MCP client to point at the socket path printed on startup.

rpc starts a JSON-RPC server that other processes can drive programmatically - useful for CI pipelines and multi-agent orchestration.

Harness CLI

The harness CLI (packages/harness-cli/) provides headless session management:

# Run a session headlessly
harness run "Build a REST API"

# Inspect a past session
harness inspect <session-id>

# Check system health
harness doctor

# List recent sessions
harness sessions

Configuration Paths

Environment Variables