Terrain

Terrain prepares the ground so agents don't have to guess where to stand.

Engineering environment management for human developers and AI coding assistants — knowledge as the map, tools as the roads, conventions as the trail markers.

What is Terrain?

Terrain is a standardized, AI-friendly engineering environment built for the age of AI-assisted development. Point it at a Git repository and it delivers three things:

• 🗺️ Engineering knowledge — auto-generated, always-in-sync C4 docs and agent context, produced from your code and consumed by both humans and AI agents.
• 🤝 A standardized environment for AI agents — one shared "knowledge contract" (Skills, AGENTS.md, CLIs) so every coding agent reads the project the same way instead of blind-grepping the live repo.
• ⚙️ Auto-deployed agent enhancement tools — one command installs the toolchain your agents need (CodeGraph, RTK, preset Skills); no per-repo yak-shaving.

Terrain provides both GUI and CLI modes. Through the CLI, you can conveniently integrate engineering knowledge generation and Deepwiki's Q&A functionality into PR and CI/CD pipelines. Human developers use the Tauri desktop app or CLI. For specific usage of the CLI, see Terrain CLI Guides.

App preview

Project overview	Engineering knowledge	DeepWiki Q&A	Agent environment

From left to right: project list with freshness scores, auto-generated C4 docs, knowledge-grounded Q&A, and one-command agent tooling setup.

Three pillars at a glance

Dual-track knowledge

Knowledge factory

Why Terrain?

Onboarding to a new codebase usually means days of reading source and stale wiki pages. Terrain compresses that to minutes: register a repo, run initialization, and get a full C4 doc set plus an agent-ready context pack.

Built for:

• Developers exploring or documenting a codebase
• Tech leads who want architecture docs that stay close to the code
• Teams adopting AI coding assistants and need a shared knowledge contract
• CI/CD pipelines that regenerate knowledge assets on merge
• ACP integrators wiring terrain tools into Claude Code, Codex, OpenCode, or compatible agents

From Litho (deepwiki-rs) to Terrain

Terrain's knowledge engine is the direct successor of Litho, the AI documentation generator published as deepwiki-rs (1.7k★). Litho proved the core thesis at scale — generate architecture docs from code, keep them in sync, make them agent-ready. Terrain takes that successful practice and hardens it into a platform:

• Incremental knowledge-base updates. Instead of regenerating from scratch, Terrain tracks Git HEAD and working-tree state and updates only what changed, so the knowledge base stays fresh on every commit without the full cost (freshness scoring + resumable pipelines).
• Broad language & framework adaptation. The generation core is language-agnostic and tuned for Rust, TypeScript/JavaScript, Python, Go, Java, C#, and more, with framework-aware structure extraction.
• ACP mode for your agents. Terrain speaks the Agent Client Protocol, so Claude Code, Codex, OpenCode, and Cursor can pull project knowledge through terrain tools instead of guessing.
• Litho Book, built in. The original Litho Book Markdown reader and its knowledge-grounded Q&A are now integrated into the Terrain desktop app — browse and ask in one place.

In short: if you liked Litho for docs, Terrain is Litho's knowledge core plus the environment, workflow, and agent bridge around it.

Features & Capabilities

1. Engineering knowledge assets — generate & consume

Terrain turns a codebase into a dual-track knowledge base that both people and agents use. Born from Litho (deepwiki-rs, 1.7k★), it keeps the proven doc-generation core and adds incremental, multi-language, agent-connected delivery.

• Generate — a four-phase pipeline produces six standard human docs (overview, architecture, workflows, deep module exploration, boundary interfaces, database overview) plus a structured agent/context.md and a grep-friendly repomix.md source pack.
• Consume — DeepWiki answers natural-language questions over the knowledge base with citations and tool-call traces; external agents consume the same three layers through terrain tools.
• Stay fresh — incremental regeneration on code change and a freshness score that flags stale assets.
• Read & ask in one place — the integrated Litho Book reader and Q&A (formerly a separate tool) now live inside the desktop app.

The same Litho success story, now incremental, multi-language, and wired to your agents.

2. Standardized, AI-friendly engineering environment

A shared "knowledge contract" so every coding agent reads your repo the same way:

• AGENTS.md — managed snippets that point agents to the knowledge layers first.
• Preset Skills — standard playbooks (terrain-knowledge → repomix → codegraph → rtk) your agents can load.
• Conventions as trail markers — consistent workflow and access patterns across repositories.

3. Auto-deployed agent enhancement tools

One command wires up the toolchain your agents need — no per-repo setup:

• CodeGraph — symbol callers/callees/impact queries via bunx codegraph.
• RTK — shell-output token optimizer that saves agents tokens.
• Terrain CLI / terrain tools — scan, assets, and ACP access.
• terrain env apply installs Skills, CLIs, and AGENTS.md in the right dependency order (terrain-knowledge → repomix → codegraph → rtk).

4. SDD — standardized development workflow

Four sequential phases, each producing a reviewable Markdown artifact:

Session outputs live under ~/.terrain/sdd/{project}/sessions/{id}/outputs/ (local, not versioned).

5. Freshness tracking

Git HEAD and dirty-state monitoring score knowledge assets. Agents should down-weight context when freshness_score < 50.

Architecture

Terrain is an agent-first engineering environment platform. For each Git repository it delivers three coordinated solutions:

Knowledge as the map, tools as the roads, conventions as the trail markers.

Humans use the desktop app or CLI; external coding agents (Claude Code, Codex, OpenCode, …) use the same contract via terrain tools (JSON stdout). Assets live in-repo (.terrain/ travels with branches); ~/.terrain/registry.json holds project pointers only.

System overview

① Engineering knowledge assets — the map

Dual-track assets from one factory — narrative human/ for people, structured agent/ for machines:

.terrain/
├── agent/context.md    macro overview
├── agent/repomix.md    grep-friendly source pack
├── human/              engineering knowledge docs (from Litho)
├── knowledge/          domain glossary
└── .meta/freshness.json

Produce (scan/pack are offline; LLM/ACP where noted):

Git ──scan──► index.md
    ──pack──► repomix.md
    ──context (LLM)──► context.md
    ──docs (ACP)──► human/ + .litho-agent/ checkpoints
    ──track──► freshness.json

Consume — DeepWiki and terrain tools share the same three layers:

When sources conflict: repomix > CodeGraph > context.md > human/. Down-weight macro context when freshness_score < 50.

② Standardized AI environment — the roads

terrain env apply installs the navigation layer so agents don't improvise:

③ Development workflow — the trail markers

SDD defines a repeatable path; each phase produces a reviewable Markdown artifact:

The knowledge pipeline uses the same resumable pattern — research checkpoints under .terrain/.litho-agent/.

Runtime

graph LR
    Chan[Desktop · CLI] --> Intel[terrain-agent]
    Chan --> Core[terrain-core]
    Intel --> Core
    Intel --> LLM[LLM]
    Intel --> ACP[ACP]
    Core --> FS[".terrain/ · Git · registry"]

Core handles scan, pack, search, freshness, and env without an LLM. Agent orchestrates DeepWiki, knowledge generation, SDD, and context generation — lightweight tasks via native LLM, heavy tool-using work via ACP subprocess.

.terrain/ directory (per project)

{your-repo}/.terrain/
├── index.md                 # Project index (from scan)
├── agent/
│   ├── context.md           # Macro architecture context for agents
│   ├── repomix.md           # Source pack (generated, often gitignored)
│   └── meta.json            # Pack metadata
├── human/                   # Engineering knowledge docs (1.概述.md, 2.架构.md, …)
├── knowledge/               # Domain glossary and conventions
├── .meta/
│   ├── sync.json            # Scan sync state
│   └── freshness.json       # Asset freshness scores
└── .litho-agent/            # Litho/knowledge research workspace (transient)

Project registration (slug ↔ repo path) is stored locally at ~/.terrain/registry.json — pointers only, not knowledge files.

Ecosystem

Terrain composes with the tools your AI workflow already uses:

Trust model for coding agents: when sources conflict, repomix source > codegraph > context.md > human docs.

Getting Started

Use Prebuilt Installer (Recommend)

Recommend downloading the pre-compiled software package from the Github Release, ready to use out of the box.

Build from source (Optional & DIY)

Prerequisites

• Rust 1.94+ (rust-toolchain.toml pins the version)
• NodeJS /Bun — Node toolchain for frontend and optional tools
• LLM access (optional) — OpenAI-compatible API, Ollama, or LM Studio (configure in the desktop app Settings panel)
• Mainstream coding agent — e.g. Codex, DeepSeek Harness, or Claude Code, for knowledge composition and SDD codegen

Build

# Clone and install frontend dependencies
git clone https://github.com/sopaco/terrain.git
cd terrain
bun install

# Build Rust workspace (CLI + libraries)
cargo build --release

# CLI binary
./target/release/terrain --help

# Desktop app (development)
bun run dev:app

License

MIT — see LICENSE.