# Context > Standalone CLI and MCP server for deterministic repository context. # Context Source: https://context.timmo.dev/ `context` gives agents and humans one command for the repository facts they usually gather with many shell calls. **Git context** Branch, pull request, working-tree, diff, and recent-commit context in one deterministic snapshot. **Stack detection** Language, ecosystem, tooling, and framework detection from repository files, with no LLM and no external scanners. **MCP server** The same producers exposed over stdio as read-only MCP tools and resources for agent harnesses. **Generated references** CLI help, shell completions, and MCP tool docs generated from the same source metadata. ## Start Here **[Install](/install)** Install from the AUR or build the binary locally with mise. **[Quick Start](/quick-start)** Run the core CLI commands and start the MCP server. **[CLI](/cli)** Use context directly from a terminal or script. **[MCP Server](/mcp)** Expose context to MCP-compatible agents over stdio. ## Documentation Scope Generic CLI and MCP behaviour lives here. OpenCode plugins that inject this context into sessions live in [`timmo001/dotfiles`](https://github.com/timmo001/dotfiles), with integration notes in the [dotfiles docs](https://dotfiles.timmo.dev/opencode/). ## Machine-readable docs | URL | Use | | --------------------------------------- | ---------------------------------------- | | https://context.timmo.dev/llms.txt | Compact page index | | https://context.timmo.dev/llms-full.txt | Full docs bundle | | https://context.timmo.dev/mcp | Hosted MCP (search, page and navigation) | | `/{route}.md` | One page as Markdown | --- # CLI Source: https://context.timmo.dev/cli The `context` CLI is the direct interface to the same producers exposed through MCP. ```bash context git context stack context mcp ``` Use `context help` or `context --help` for terminal help. The [command reference](/cli/commands) is generated from the same CLI registry. Argument parsing is strict. Unknown or repeated options, missing values, invalid fixed choices, and extra positional arguments return a usage error. Use `--` before a positional path that begins with a hyphen. Git and GitHub subprocesses default to a 30-second timeout and a 16 MiB aggregate output limit. Set `CONTEXT_COMMAND_TIMEOUT_MS` or `CONTEXT_COMMAND_MAX_OUTPUT_BYTES` to non-negative integer values when a repository needs different limits. Shell completions are generated by [`context completions`](/cli/completions). --- # Command Reference Source: https://context.timmo.dev/cli/commands This page lists every `context` command, generated from the same registry that powers `context help`. ## `context git` Show branch context for the current repository ```text context git [options] ``` Print branch context for the current git repository: repository root, branch/base header, HEAD, ahead/behind state, pull request summary for feature branches, working-tree status, branch work-scope, recent commits, and optional full diffs. Designed as a single command for agents to get full working-tree and branch context, and as the shared producer for the git_context MCP tool. **Modes** ```text (default) Context summary: repo, branch, PR, status, branch files, commits --json Emit the structured branch-context payload --diff Also print full unstaged and staged diffs --branch-diff Also print the full diff vs the default branch --remotes Also include remote fetch/push URLs --since Show recent commits since a date instead of the default window ``` **Options** | Option | Description | | ---------------------- | -------------------------------------------------------- | | `--json` | Emit the structured plugin payload instead of text | | `--comments` | Include pull request conversation comments | | `--reviews` | Include individual pull request reviews | | `--labels` | Include pull request labels | | `--checks` | Include CI check runs (makes a second gh call) | | `--no-description` | Omit the pull request description | | `--no-pr` | Omit the pull request block entirely | | `--remotes` | Include remote fetch/push URLs in branch metadata | | `--no-branch-metadata` | Omit the branch metadata block | | `--no-status` | Omit the working-tree status block | | `--no-work-scope` | Omit the branch work-scope block | | `--diff` | Append full unstaged and staged diffs for changed files | | `--branch-diff` | Append the merge-base diff vs the default branch | | `--since` `` | Show recent commits since this date or relative duration | **Examples** ```bash context git context git --comments --reviews context git --labels --checks context git --remotes context git --diff context git --branch-diff context git --json context git --since "2 days ago" ``` ## `context stack` Detect the tech stack of a directory for agents ```text context stack [dir] [options] ``` Detect a directory's tech stack deterministically from Git-listed files, with no LLM and no external tools: languages, package ecosystems, tooling, and frameworks. Designed as a single command for agents to learn a project's stack, and as the shared producer for the stack_context MCP tool. **Modes** ```text (default) Stack summary: languages, ecosystems, tooling, frameworks --json Emit the structured stack-context payload --plain Disable ANSI styling in text output ``` **Options** | Option | Description | | --------- | -------------------------------------------------- | | `--json` | Emit the structured plugin payload instead of text | | `--plain` | Disable ANSI styling in text output | **Arguments** | Argument | Description | | -------- | ------------------------------------------------------ | | `` | Directory to scan (default: current working directory) | **Examples** ```bash context stack context stack --plain context stack --json context stack ~/projects/app ``` ## `context mcp` Run the context MCP server over stdio ```text context mcp ``` Start a Model Context Protocol server exposing git_context, stack_context, and command_help tools plus read-only context resources. **Examples** ```bash context mcp ``` ## `context agent` List or run the Code Mode tools the OpenCode plugin registers ```text context agent tools [--json] | call ``` The Code Mode surface for agent plugins. `agent tools` prints every tool with its input schema as JSON. `agent call ` runs one in the current directory, with its input as JSON on stdin, and prints its result as JSON. **Options** | Option | Description | | -------- | ---------------------------- | | `--json` | Print JSON (the only format) | **Arguments** | Argument | Description | | ---------- | --------------------------------------------------------------------- | | `` | tools to list the tools, or call to run one. One of: `tools`, `call`. | | `` | The tool to run, from context agent tools. One of: `git`, `stack`. | **Examples** ```bash context agent tools --json echo '{"comments":true}' | context agent call git ``` ## `context completions` Generate shell completions ```text context completions [bash|fish|zsh] ``` Generate shell completions for context. **Arguments** | Argument | Description | | --------- | ------------------------------ | | `` | One of: `bash`, `fish`, `zsh`. | **Examples** ```bash context completions zsh context completions bash context completions fish ``` ## `context help` Show context help ```text context help [command] ``` **Arguments** | Argument | Description | | ----------- | ----------------------------------------------------------------------------------------- | | `` | Optional command to show help for. One of: `git`, `stack`, `mcp`, `agent`, `completions`. | **Examples** ```bash context help context help git ``` --- # Shell Completions Source: https://context.timmo.dev/cli/completions `context` can print completion scripts for Bash, Fish, and Zsh: ```bash context completions context completions bash context completions fish context completions zsh ``` With no shell argument, `context completions` prints Zsh completions. The Arch packages install Bash, Fish, and Zsh completions automatically. For a local binary, write the generated script into the shell-specific completion directory for your environment. --- # Git Context Source: https://context.timmo.dev/context/git `context git` prints a compact snapshot of the current Git repository. It replaces separate calls to `git status`, `git diff --stat`, `git diff --cached --stat`, `git log --oneline --stat`, `git log @{upstream}..HEAD`, and selected `gh pr` commands. ```bash context git context git --comments --reviews context git --labels --checks context git --remotes context git --diff context git --branch-diff context git --json context git --since "2 days ago" ``` The text output includes repository identity, branch/base refs, ahead/behind state, working-tree file lists with line counts, branch changed files, recent commits with pushed/local markers, and an optional pull request block. The default remote is chosen from `upstream`, then `origin`, then the first configured remote. HTTP remote credentials are stripped before remote URLs are printed. `context git` does not assume a branch named `main`. If the remote default branch cannot be resolved, the JSON payload records nullable default/base fields and an explicit unresolved work-scope state. Comparisons and pull request lookup that depend on that branch are skipped with warnings. `--json` emits the structured payload consumed by OpenCode context plugins. Full diffs from `--diff` and `--branch-diff` are text-only and are intentionally ignored for JSON output. Large metadata, status, commit, and pull request sections are bounded; applied limits are included as structured truncation notices. ## Recent Commits On a feature branch, `context git` lists commits unique to the branch. On the default branch, it lists today's commits, capped at 20, but still shows at least the last 10 commits when there are fewer commits today. Use `--since ` on the default branch to replace that default recent-commit window with a date or relative duration. Feature branches keep the branch-only commit range so the snapshot stays scoped to the branch. ## Sections Use `--no-pr`, `--no-description`, `--no-branch-metadata`, `--no-status`, and `--no-work-scope` to omit sections when a smaller snapshot is needed. ## Pull Requests On a feature branch, `context git` attempts to read the pull request with `gh pr view`. The PR lookup is resilient: missing `gh`, a missing PR, or network errors do not fail the command. Extra PR sections are opt-in with `--comments`, `--reviews`, `--labels`, and `--checks`. Git data required for an enabled section is not optional. If status, commit, work-scope, or requested diff collection fails, the command fails instead of presenting an empty section as authoritative. ## Full Diffs Use `--diff` for unstaged and staged diffs. Use `--branch-diff` for the merge-base diff against the default branch. `--branch-diff` errors on the default branch because there is no feature branch range to show. --- # Stack Context Source: https://context.timmo.dev/context/stack `context stack` detects a repository's tech stack from Git-listed files with no LLM and no external scanners. ```bash context stack context stack --plain context stack --json context stack ~/projects/app ``` Detection uses `git ls-files --cached --others --exclude-standard --deduplicate`, respects Git ignore rules, and excludes known generated and vendored directory segments even when they are tracked. It returns a warning instead of a partial guess when the target is not a readable Git worktree. It reads bounded regular-file manifests without following symlinks, classifies known config and lockfile paths, and takes an extension/filename census. It reports: - Languages with top general locations. - Package ecosystems from manifests. - Tooling from lockfiles, config files, and declared dependencies. - Frameworks from declared dependencies. `--json` emits the structured payload consumed by agent integrations. The JSON renderer caps list lengths and individual values so large repositories cannot inflate prompts unexpectedly. The scanner is intentionally bounded. It records structured `truncations` for file-list bytes, depth, file count, manifest reads, collected evidence, and renderer output. Each record identifies the limit and includes observed or omitted counts when they are known. Dependencies are parsed from their declared sections in `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, requirements files, `Pipfile`, and conservative literal lists in `setup.py`. Comments and unrelated manifest text are not treated as dependency evidence. --- # Install Source: https://context.timmo.dev/install ## Arch Linux Install the stable binary package with an AUR helper: ```bash yay -S context-bin ``` Install `context-git` instead to track relevant changes on `main`: ```bash yay -S context-git ``` Both packages install the `context` binary plus Bash, Fish, and Zsh completions. Stable releases use a semver version shared by the CLI and `@timmo001/effect-context`. Create a blank GitHub draft tagged with it, optionally generate its release notes, then publish it to build Linux archives, deb and RPM packages, publish the library to npm and JSR, and update `context-bin`. ## Runtime Requirements Release binaries are standalone and do not require Bun, Node.js, or npm packages at runtime. `context` uses these external commands: - `git` is required for Git and stack context. - `gh` is optional. It adds GitHub pull request context when available; missing `gh`, a missing pull request, or a network error does not fail the command. ## Release Assets Download stable archives, deb packages, and RPM packages from the [GitHub releases page](https://github.com/timmo001/context/releases). Archives contain the standalone `context` executable. Deb, RPM, and AUR packages also install Bash, Fish, and Zsh completions. Install a downloaded deb or RPM package with your system package manager: ```bash sudo apt install ./context_VERSION_ARCH.deb sudo dnf install ./context-VERSION-1.ARCH.rpm ``` ## Build Locally Use the mise tasks to install dependencies and build the binary. The repo pins Node and Bun through mise. ```bash mise run install mise run build ``` The compiled binary is written to `dist/context`. Run it directly or put it somewhere on your `PATH`: ```bash ./dist/context --help ``` --- # OpenCode Source: https://context.timmo.dev/integrations/opencode `context` owns the generic CLI, MCP server and OpenCode plugin. ## Plugin The OpenCode plugin in `opencode-plugin/` adds a `context` Code Mode namespace, so an agent can read the session repository's branch context and tech stack in one script. Load it from the repository: ```json { "plugins": ["github:timmo001/context#main::path:opencode-plugin"] } ``` It reads its tools from `context agent tools --json` and runs each with `context agent call` in the session's directory, so they always match the `context` on your `PATH`. Both tools only read. ## CLI Other integrations can call the CLI directly: ```bash context git --json context stack --json ``` --- # MCP Server Source: https://context.timmo.dev/mcp/server `context mcp` starts a Model Context Protocol server over stdio. It speaks JSON-RPC on stdout and sends logging to stderr so the protocol stream stays clean. ```json { "mcp": { "context": { "type": "local", "command": ["context", "mcp"], "enabled": true } } } ``` The server exposes read-only tools and resources. `git_context` validates `since` with the same parser as the CLI and is marked open-world when its default pull request lookup may access GitHub. See the generated [MCP tool reference](/mcp/tools) for tool parameters. ## Resources - `context://git` - default text output from `context git`. - `context://stack` - default text output from `context stack`. - `context://command/{name}` - help text for a context command. ## Results and Code Mode `git_context` and `stack_context` declare an `outputSchema` and return `structuredContent` alongside the usual text. The structured result is the same bounded payload as `context git --json` and `context stack --json`, so the full diffs from `diff` and `branchDiff` stay in the text only. `command_help` returns plain help text and has no output schema. Clients that type tools from their output schema, such as OpenCode's Code Mode, can chain calls on the fields: ```js const git = await tools["context"].git_context({ pullRequest: false }); const stack = await tools["context"].stack_context({ dir: git.branchMetadata?.repositoryRoot, }); return { branch: git.branchMetadata?.currentBranch, frameworks: stack.frameworks.map((framework) => framework.name), }; ``` --- # MCP Tool Reference Source: https://context.timmo.dev/mcp/tools ## `git_context` Concise branch context for the current repository, with optional PR detail, remote URLs, working-tree diffs, and merge-base branch diff. CLI equivalent: `context git` | Parameter | Type | Default | CLI | Description | | ------------- | ------- | ------- | ----------------------- | --------------------------------------------------------------------------------- | | `diff` | boolean | false | `--diff` | Append the full unstaged and staged diffs beneath each working-tree section. | | `branchDiff` | boolean | false | `--branch-diff` | Append the full merge-base diff of the current branch against the default branch. | | `comments` | boolean | false | `--comments` | Include pull request conversation comments. | | `reviews` | boolean | false | `--reviews` | Include individual pull request reviews. | | `labels` | boolean | false | `--labels` | Include pull request labels. | | `checks` | boolean | false | `--checks` | Include CI check runs. | | `description` | boolean | true | `omit --no-description` | Include the pull request description. | | `pullRequest` | boolean | true | `omit --no-pr` | Include the pull request block at all. | | `remotes` | boolean | false | `--remotes` | Include remote fetch/push URLs in branch metadata. | | `since` | string | | `--since ` | Only include recent commits after this date. | ## `stack_context` Deterministic tech-stack summary for a directory: languages, ecosystems, tooling, and frameworks. CLI equivalent: `context stack` | Parameter | Type | Default | CLI | Description | | --------- | ------ | ------- | ------- | ----------------------------------------------------------------------- | | `dir` | string | | `[dir]` | Directory to scan. Omit to scan the server's current working directory. | ## `command_help` Show context CLI help. Omit name for the full command overview, or pass a command name to scope help. CLI equivalent: `context help [name]` | Parameter | Type | Default | CLI | Description | | --------- | ------ | ------- | -------- | ---------------------------------- | | `name` | string | | `[name]` | Optional command to scope help to. | --- # Quick Start Source: https://context.timmo.dev/quick-start Install `context` first, or build locally and substitute `./dist/context` for `context` in the examples below. Use `context git` to inspect the current repository state: ```bash context git context git --json ``` Use `context stack` to detect the repository stack: ```bash context stack context stack --json ``` Start the MCP server over stdio: ```bash context mcp ``` The MCP server exposes the same producers through `git_context`, `stack_context`, and `command_help` tools. ## Next Steps - Read the [CLI overview](/cli) for terminal usage. - Read the [Git Context](/context/git) and [Stack Context](/context/stack) pages for producer details. - Read the [MCP Server](/mcp/server) page for agent integration.