terrain

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.

English · 简体中文 App preview *From left to right: project list with freshness scores, auto-generated C4 docs, knowledge-grounded Q&A, and one-command agent tooling setup.* Contents What is Terrain? Install Getting started CLI command reference Why Terrain? Architecture Ecosystem From Litho to Terrain License What is Terrain?

Terrain is a standardized, AI-friendly engineering environment. Point it at a Git repository and it delivers three things: 🗺️ Engineering knowledge — always-in-sync C4 docs and agent context, produced from your code and consumed by both humans and AI agents. 🤝 A shared agent contract — Skills, AGENTS.md, and CLIs, so every coding agent reads the project the same way instead of blind-grepping the live repo. ⚙️ Auto-deployed tooling — one command installs what your agents need (CodeGraph, RTK, preset Skills); no per-repo yak-shaving.

It runs as a desktop app (GUI) or a CLI — see Getting started for which to pick. Three pillars One codebase, two audiences: Knowledge factory

Why it stands out Incremental — tracks Git HEAD and regenerates only what changed, not the whole knowledge base. Freshness-scored — every asset carries a score; agents down-weight context below 50. One contract for every agent — Claude Code, Codex, OpenCode, and Cursor read the same layers through terrain tools. Toolchain in one command — terrain env apply installs CodeGraph, RTK, and preset Skills in dependency order. Reviewable workflow — SDD turns requirements → design → codegen → review into Markdown artifacts. Performance & integration Native Rust core — a single binary, no runtime, no database. Scan, pack, search, freshness, and env run fully offline with no LLM call. Cross-platform — prebuilt desktop installers for macOS (Apple Silicon) and Windows x64, plus @terrain-ai/cli on npm for headless machines and CI. Pipeline-friendly — JSON stdout on every terrain tools call and NDJSON event streaming from terrain ask query --stream, so Terrain drops into CI jobs, PR checks, and agent loops without glue code. Install Option 1 — Prebuilt installer (recommended)

Download the package for your platform from GitHub Releases and open it — no Rust or Node toolchain required. Unsigned builds — first-launch notice. The installers are not yet signed with an Apple Developer ID / Authenticode certificate, so both platforms raise a one-time warning. The download is intact; see below to continue. macOS — "Terrain is damaged / should be moved to the Trash"

This is Gatekeeper, not a corrupt file. Downloads from the internet carry a com.apple.quarantine attribute, and macOS refuses to launch an unsigned app with that flag set. Remove the flag after copying Terrain.app to /Applications:

Windows — SmartScreen "Windows protected your PC"

Click More info → Run anyway. The prompt appears once per build. Option 2 — Build from source

Use this path for unsupported platforms, custom patches, or contributing to Terrain itself. Prerequisites Rust — stable toolchain (MSRV 1.94; see rust-toolchain.toml) Node.js / Bun — frontend toolchain and optional Node-based tools LLM access (optional) — OpenAI-compatible API, Ollama, or LM Studio (configure in the desktop app Settings panel) Mainstream coding agent (optional) — e.g. Codex, DeepSeek Harness, or Claude Code, for knowledge composition and SDD codegen Build Getting started Which entry point should I use? Path A — Desktop app (start here)

The app bundles the full loop, so there is nothing to compose yourself.

1. Install and open Terrain (see Install). 2. Add a project — point Terrain at a local Git repository. 3. Run initialization — Terrain scans the repo, generates the six C4 docs, and writes .terrain/. 4. Read