Immanence resolves a repo, pins a commit, downloads a cached source snapshot, and answers your question with file-level citations tied to that commit.

im·ma·nence /ˈimənəns/ The quality of being contained within; inherent. Here, answers come from the pinned codebase itself.

How It Works

 You ask a question
       ↓
 Repo is resolved (or inferred from the question)
       ↓
 HEAD is pinned to a specific commit SHA
       ↓
 Source snapshot is downloaded & cached locally
       ↓
 The agent inspects the code with tool calls
       ↓
 You get an answer with file + line citations

Three interfaces, same engine:

| Interface | Use case | |-----------|----------| | CLI | One-off questions from your terminal | | HTTP | Integrate into scripts, bots, dashboards | | MCP | Plug into any MCP-compatible AI assistant |

Quick Start

Requirements

• Node.js 24+
• git on your PATH

Install & Build

npm install
npm run build

Authenticate

npx immanence auth login
npx immanence auth status   # verify

Ask Something

# Specify a repo explicitly
npx immanence ask \
  --repo honojs/hono \
  --question "How does the router match params and wildcards?"

# Let Immanence figure out which repo you mean
npx immanence ask \
  --question "Where does Next.js get its list of Google fonts?"

# Machine-readable output
npx immanence ask \
  --question "Where does Next.js get its list of Google fonts?" \
  --json

CLI Reference

Commands

| Command | Description | |---------|-------------| | auth login | Authenticate with GitHub | | auth status | Check authentication state | | auth logout | Clear stored credentials | | models | List available models | | ask | Ask a question about a codebase | | serve http | Start the HTTP server | | serve mcp | Start the MCP server |

ask Options

| Flag | Description | |------|-------------| | --repo <repo...> | One or more GitHub repos (owner/name) | | --ref <ref> | Branch, tag, or commit SHA | | --model <model> | Override the default model | | --include-web-search | Augment with Brave web search | | --refresh <mode> | never · if-stale · always | | --max-tool-calls <n> | Cap the number of tool calls | | --json | Emit the full response envelope as JSON |

HTTP API

npm run serve:http   # default: 127.0.0.1:8787

| Method | Endpoint | Purpose | |--------|----------|---------| | GET | /healthz | Health check | | GET | /v1/auth/status | Auth state | | GET | /v1/models | Available models | | POST | /v1/questions | Ask a question |

Example request:

curl -s -X POST http://127.0.0.1:8787/v1/questions \
  -H 'content-type: application/json' \
  -d '{
    "question": "How does the router match params and wildcards?",
    "repos": [{ "repo": "honojs/hono" }]
  }' | jq .

MCP Server

npm run serve:mcp

Exposes a single tool — ask_codebase_question — that any MCP-compatible client can call.

Platform Notes

Windows

Natively supported. Requires git on PATH.

| Path | Default | |------|---------| | Data | %LOCALAPPDATA%\immanence\data | | Cache | %LOCALAPPDATA%\immanence\cache |

Storage & Environment

| Variable | Purpose | Default (Linux/macOS) | |----------|---------|-----------------------| | IMMANENCE_DATA_DIR | Persistent data | ~/.local/share/immanence | | IMMANENCE_CACHE_DIR | Cached snapshots | ~/.cache/immanence | | IMMANENCE_DEFAULT_MODEL | Default model | (built-in) | | BRAVE_SEARCH_API_KEY | Web search augmentation | (disabled) |

Repo snapshots live under $IMMANENCE_DATA_DIR/repos/github.com/… and are keyed by commit SHA.

Limits

• Public GitHub repos only.
• Read-only inspection — Immanence never modifies code.
• No chat memory between questions.

Contributing

npm run dev -- --help   # run from source
npm test                # run the test suite
npm run build           # production build

Snapshots are cached by commit SHA. Refs are refreshed according to --refresh. Final answers always include the pinned SHA so citations stay stable over time.

License

MIT © Kaf