Terrain — prepares the ground so agents don't have to guess where to stand. 🔗 GitHub: https://github.com/sopaco/terrain The Real Problem in CI/CD Pipelines Teams often face these issues in CI pipelines: Regenerate documents on every merge—but only a few files actually changed Knowledge assets drift from code unnoticed—until an AI assistant gives wrong suggestions based on stale information Every CI environment requires manual toolchain installation—CodeGraph, RTK, Skills configured repeatedly Pipeline output is hard to integrate into Agent workflows—information needs conversion to Agent-understandable formats Terrain's design philosophy is built for automation: JSON output, incremental refresh, headless operation, one-click toolchain deployment. Core Capability: CLI-First, JSON Everywhere All Terrain commands are designed to be callable directly in scripts and pipelines: JSON standard output — Every terrain tools command outputs JSON, no custom format parsing needed. NDJSON event streams — terrain ask query --stream outputs line-by-line JSON events for real-time streaming consumption. Headless operation — CLI doesn't depend on any display service, runs in pure terminal environments. Typical CI Usage: Auto-Refresh Knowledge on Merge # In CI script: auto-refresh knowledge assets after merge terrain refresh . # Output project freshness to logs terrain project freshness-cached --project my-repo # If freshness is below threshold, mark as warning terrain tools freshness --project my-repo | jq '.score' This means after every code merge, knowledge assets update automatically with no manual intervention. New team members who clone the repository see everything up-to-date. Environment Standardization: terrain env apply One-Click Deploy In CI or new environments, one command installs all Agent toolchains: # Preview components to be installed terrain env plan # One-click install: Skills, CodeGraph, RTK, AGENTS.md snippets terrain env apply # Verify installation status terrain env status Component Description Skills Standardized workflow instructions (knowledge queries, SDD, Ask, architecture analysis) CodeGraph Symbol call graph RTK Compresses shell output, saves tokens AGENTS.md Unified project convention snippets Terrain's environment configuration interface. One click deploys standardized toolchains for all Agents. Cross-Platform Distribution: npm + Pre-compiled Installers Method Use Case Installation npm package CI/CD, headless servers, Agent pipelines npm install -g @terrain-ai/cli Pre-compiled installer Local development, desktop use Download from GitHub Releases Node.js shim Tool calls in npm environments Auto-installed macOS (Apple Silicon) and Windows x64 both have pre-compiled binaries @terrain-ai/cli and @terrain-ai/rtk are both installable globally via npm Desktop app is packaged via Tauri, includes CLI—no extra installation needed Core Technology: Why Is It Pipeline-Friendly? Native Rust Core, Runs Offline All core computation is handled by terrain-core (pure Rust): No runtime dependencies — Single binary, no dependency on Node.js/Python/databases. Offline execution — scan, pack, search, freshness don't call LLMs. Deterministic output — Same input produces same JSON output, suitable for automated assertions. Incremental Refresh Engine graph TD Git[Git Code Repository] --> Scan[ProjectScanner<br/>Collect Git Metadata] Scan --> Changed{Which Files Changed?} Changed -->|Changed Files| Repack[repomix Repack] Changed -->|Changed Modules| Update[Update Corresponding C4 Docs] Changed -->|No Changes| Skip[Skip Document Generation] Repack --> Context[Update context.md] Update --> Score[Recalculate Freshness Score] Score --> Output[Output JSON Result] style Skip fill:#d4f4e2,stroke:#2a9 Only processes what changed—this is the core difference between incremental refresh and traditional full regeneration. For a 100K-line project, if only a few files are modified, refresh might take just seconds. Pipeline-Friendly Output Format # JSON output can be processed directly by jq/scripts terrain tools read-context --project my-repo | jq '.modules[].name' # NDJSON stream can be consumed in real-time terrain ask query "How does the system handle requests?" --project my-repo --stream | while read line; do echo "$line" | jq '.type' done # Suitable for CI logs and assertions terrain project freshness-cached --project my-repo > freshness.json Complete CI Example #!/bin/bash # .github/workflows/terrain-knowledge.yml name: Update Knowledge Assets on: [push, pull_request] jobs: refresh-knowledge: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Terrain CLI run: npm install -g @terrain-ai/cli - name: Refresh knowledge assets run: | terrain refresh . terrain project freshness-cached --project my-repo - name: Check freshness threshold run: | SCORE=$(terrain project overview --project my-repo | jq '.freshness_score') if [ "$SCORE" -lt 50 ]; then echo "::warning::Knowledge assets are stale (score: $SCORE)" fi Who Is This For? DevOps Engineers — Integrate knowledge asset updates into CI pipelines. Platform Teams — Standardize Agent environments across all projects. Large-scale Teams — New repositories automatically get knowledge assets, no manual configuration. ACP Integrators — Connect terrain tools JSON API to automated Agent loops. Open Source Maintainers — Let contributors clone and immediately have full project knowledge. "JSON output, incremental refresh, one-click deploy—a knowledge pipeline built for automation."