Skip to main content
Glama
JeremyJiao01

Terrain

by JeremyJiao01
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Terrain

English | Chinese / CN

CI PyPI npm License Python Node

Give your AI coding assistant a complete map of any codebase — function signatures, call graphs, and semantic search across every line of code.

The Problem

You drop a 500,000-line codebase in front of Claude Code. It reads what it can see. It guesses what it can't. You get answers that are almost right.

Terrain indexes the entire codebase once, then gives your AI a precise, queryable knowledge graph — so it stops guessing.

Related MCP server: CodeGraph

What This Looks Like

Ask Claude Code about an unfamiliar codebase:

"How does the authentication token get refreshed?"

Without Terrain, the AI skims files and makes educated guesses — possibly missing the real implementation buried three call levels deep.

With Terrain:

find_api("authentication token refresh")

→ refresh_access_token() in auth/token_manager.c:187
  Signature: int refresh_access_token(TokenCtx *ctx, const char *refresh_token)
  Called by: session_heartbeat() → event_loop_tick() → main()
  Calls:     http_post(), parse_jwt(), update_session_store()

Precise. Complete. Instant.

Full Installation

Install the npm package

The npm package provides the CLI wrapper and MCP server launcher:

npm install -g terrain-ai@latest

Install the Python package (PyPI)

The Python package provides the core indexing engine, graph database, and all language parsers.

Core installation (includes C/C++, Python, JavaScript/TypeScript grammars):

pip install terrain-ai

Quick Start — Agent Install (Recommended)

Already using an AI agent like Claude Code, opencode, or codex? Paste this into your agent chat:

Please follow the installation instructions at:
https://raw.githubusercontent.com/JeremyJiao01/Terrain-AI/main/AGENT_INSTALL.md

Your agent will handle everything: Python 3.11 check, package install, API key setup, and MCP registration. After the first run, you can re-trigger by saying "install terrain" in any session.

Manual Install (Alternative)

npx terrain-ai@latest --setup

The setup wizard installs the Python package, configures your LLM and embedding provider, and registers Terrain as a global MCP server for supported clients. One command.

Supported clients (auto-detected):

  • Claude Code — MCP registered via claude mcp add; slash commands installed to ~/.claude/commands/

  • opencode — MCP registered by editing ~/.config/opencode/opencode.json (respects $XDG_CONFIG_HOME); slash commands installed to ~/.config/opencode/command/

Index a Codebase

terrain index /path/to/your/repo

Takes a few minutes the first time. Incremental updates after that:

terrain index -i   # git-diff based, fast

What You Can Ask

You want to know...

What to ask

Where does X get initialized?

"find where X is initialized"

What calls this function?

"find callers of function_name"

How does feature Y work end-to-end?

"trace the call chain for Y"

What functions handle Z?

"find Z handler"

Supported Languages

C/C++, Python, JavaScript/TypeScript, Rust, Go, Java, Scala, C#, PHP, Lua

Reference

Uninstall

npx terrain-ai@latest --uninstall

Removes: Claude MCP registration, opencode MCP registration, slash commands from both clients, Python package, workspace data.

CLI Tool (terrain)

Workspace

terrain status              # Show active repository, workspace, LLM & embedding info
terrain list                # List all indexed repositories
terrain repo                # Interactively switch active repository
terrain config              # Interactive configuration wizard (LLM, embedding, workspace)
terrain link <path>         # Link a local repo to shared pre-built artifacts
terrain link <path> --db x  # Link to a specific artifact directory

Indexing

terrain index               # Index current directory (graph → api-docs → embeddings)
terrain index /path/to/repo # Index a specific path
terrain index -i            # Incremental update (git-diff based, fast)
terrain index --no-embed    # Skip embedding generation
terrain index --no-wiki     # Skip wiki generation only

Rebuild & Clean

terrain rebuild             # Rebuild all steps for active repository
terrain rebuild --step graph   # Rebuild only the graph
terrain rebuild --step api     # Rebuild only API docs
terrain rebuild --step embed   # Rebuild only embeddings
terrain rebuild --step wiki    # Rebuild only wiki

terrain clean               # Remove indexed data (interactive)
terrain clean repo_name     # Remove specific repository
terrain clean --all         # Remove all indexed repositories

Low-Level Commands

terrain scan /path          # Scan repo and build knowledge graph
  --backend kuzu|memgraph|memory
  --db-path ./graph.db
  --exclude "vendor,build"
  --language "c,python"
  --clean               # Clean DB before scanning
  -o graph.json         # Export graph to JSON

terrain query "MATCH (f:Function) RETURN f.name LIMIT 10"
  --format table|json

terrain export /path -o graph.json
  --build               # Build graph before exporting

terrain stats               # Show graph statistics (nodes, relationships)

Global Flags

terrain --version           # Show version
terrain -v ...              # Verbose/debug output
terrain --help              # Show help

MCP Tools

Core workflow for AI agents: initialize_repository → find_api → get_api_doc

Repository Management

Tool

Description

initialize_repository

Index a repo: graph + API docs + embeddings

get_repository_info

Active repo stats (node/relationship counts, service status)

list_repositories

All indexed repos with pipeline completion status

switch_repository

Switch active repo for queries

link_repository

Reuse existing index for a different repo path (no re-indexing)

Code Search & Documentation

Tool

Description

find_api

Hybrid semantic + keyword search with API doc (primary search tool)

list_api_docs

Browse L1 module index or L2 module details

get_api_doc

L3 function detail: signature, call tree, usage examples, source

generate_api_docs

Generate/update API docs (full / resume / enhance)

Call Graph Analysis

Tool

Description

find_callers

Find all functions that call a specific function (no LLM required)

trace_call_chain

BFS upward call chain trace with entry point discovery

Configuration & Maintenance

Tool

Description

rebuild_embeddings

Build or rebuild vector embeddings

Pipeline

Step

What

Input

Output

1. graph-build

Tree-sitter AST parsing

Source code

Kuzu graph database

2. api-doc-gen

Query graph, render docs

Graph

3-level Markdown (index / module / function)

2b. desc-gen

LLM generates descriptions

Functions without docstrings

Descriptions in L3 Markdown

3. embed-gen

Vectorize function docs

L3 Markdown files

Vector store (pickle)

initialize_repository  ->  Steps 1-3 (full pipeline)
build_graph            ->  Step 1 only
generate_api_docs      ->  Step 2 + 2b (modes: full / resume / enhance)
rebuild_embeddings     ->  Step 3
generate_wiki          ->  Separate (not in main pipeline)

API Documentation Format

Generated docs are optimized for both AI agent reading and vector retrieval.

L3 Function Detail (embedding unit)

# parse_btype

> Parse base type declaration including struct/union/enum specifiers.

- Signature: `int parse_btype(CType *type, AttributeDef *ad, int ignore_label)`
- Return: `int`
- Visibility: static | Header: tccgen.h
- Location: tccgen.c:139-280
- Module: tinycc.tccgen --C code generator

## Call Tree

parse_btype
|-- expr_const           [static]
|-- parse_btype_qualify   [static]
|-- struct_decl           [static]
|   |-- expect
|   `-- next
`-- parse_attribute       [static]

## Called by (5)

- type_decl (tinycc.tccgen) -> tccgen.c:1200
- post_type (tinycc.tccgen) -> tccgen.c:1350

C/C++ Specific Features

  • Extracts // and /* */ comments above functions as descriptions

  • Struct/union/enum members displayed with types

  • Macro definitions in dedicated section

  • Static/public/extern visibility classification

  • Memory ownership inference from signatures

  • Header/implementation file split

  • Cross-file function call resolution via #include header mapping

  • Function pointer tracking and indirect call resolution

  • GB2312/GBK encoding support for source files

Supported Languages (detail)

Language

Functions

Classes/Structs

Calls

Imports

Types

C / C++

Yes

struct, union, enum, typedef, macro

Yes

#include

Yes

Python

Yes

Yes

Yes

Yes

-

JavaScript / TypeScript

Yes

Yes

Yes

Yes

-

Rust

Yes

struct, enum, trait, impl

Yes

Yes

-

Go

Yes

struct, interface

Yes

Yes

-

Java

Yes

class, interface, enum

Yes

Yes

-

Scala

Yes

class, object

Yes

Yes

-

C#

Yes

class, namespace

Yes

-

-

PHP

Yes

class

Yes

-

-

Lua

Yes

-

Yes

-

-

Graph Schema

Nodes: Project, Package, Module, File, Folder, Class, Function, Method, Type, Enum, Union

Relationships: CONTAINS_*, DEFINES, DEFINES_METHOD, CALLS, INHERITS, IMPLEMENTS, IMPORTS, OVERRIDES

Properties: qualified_name (PK), name, path, start_line, end_line, signature, return_type, visibility, parameters, kind, docstring

Architecture

The project follows a 5-layer harness architecture:

L4  entrypoints/         MCP server, CLI
L3  domains/upper/       apidoc, rag, guidance, calltrace
L2  domains/core/        graph, embedding, search
L1  foundation/          parsers, services, utils
L0  foundation/types/    constants, models, type definitions

Environment Variables

LLM (first match wins)

Variable

Purpose

Default

LLM_API_KEY

Generic LLM key (highest priority)

-

LLM_BASE_URL

API endpoint

https://api.openai.com/v1

LLM_MODEL

Model name

gpt-4o

OPENAI_API_KEY

OpenAI or compatible

-

MOONSHOT_API_KEY

Moonshot / Kimi (legacy)

-

Embedding

Variable

Purpose

Default

DASHSCOPE_API_KEY

DashScope (Qwen3 Embedding)

-

DASHSCOPE_BASE_URL

DashScope endpoint

https://dashscope.aliyuncs.com/api/v1

System

Variable

Purpose

Default

TERRAIN_WORKSPACE

Workspace directory

~/.terrain

Installation Options

Install from PyPI

# Core (includes C/C++, Python, JS/TS grammars)
pip install terrain-ai

# With all language grammars (Rust, Go, Java, Scala, Lua)
pip install "terrain-ai[treesitter-full]"

Install from npm

# Global install (recommended for CLI usage)
npm install -g terrain-ai@latest

# Or run directly with npx (no install needed)
npx terrain-ai@latest --version

Install from local source

git clone https://github.com/JeremyJiao01/CodeGraphWiki.git
cd CodeGraphWiki

# Install with all language grammars
pip install ".[treesitter-full]"

# Or install in editable mode for development
pip install -e ".[treesitter-full]"

Build and install from wheel

git clone https://github.com/JeremyJiao01/CodeGraphWiki.git
cd CodeGraphWiki

python3 -m build
pip install dist/terrain_ai-*.whl

Development

git clone https://github.com/JeremyJiao01/CodeGraphWiki.git
cd CodeGraphWiki
pip install -e ".[treesitter-full]"

python3 -m pytest tests/ -v

# Integration tests (requires tinycc repo at ../tinycc)
python3 -m pytest tests/domains/core/test_graph_build.py -v      # ~3 min
python3 -m pytest tests/domains/upper/test_api_docs.py -v        # ~3 min
python3 -m pytest tests/domains/core/test_step3_embedding.py -v  # ~27 min (API calls)
python3 -m pytest tests/domains/upper/test_api_find_integration.py -v  # ~47 min (full pipeline)

License

Apache License 2.0 — see LICENSE for details.

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
2Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/JeremyJiao01/Terrain-AI'

If you have feedback or need assistance with the MCP directory API, please join our Discord server