# Contexo Docs

> Reference and guides for the Contexo CLI and MCP server — every command, every tool, with worked examples.

Contexo is "GitHub for AI context." Each project keeps a versioned `.contexo/` knowledge base that AI coding agents (Claude Code, Cursor, and any MCP-compatible tool) push to and pull from over MCP, so every session and every teammate starts already up to speed. The CLI and server are open source and self-hostable.

## Start here

Install, first run, and wiring an agent.

- [Connect your agent](https://docs.contexo.live/start/connect-your-agent/): What ctx init wires automatically, what you have to opt into, and how to add Contexo to any other MCP client.
- [Install](https://docs.contexo.live/start/install/): Install the ctx CLI on macOS, Linux or Windows — prebuilt checksum-verified binaries, or go install.
- [Quickstart](https://docs.contexo.live/start/quickstart/): Five minutes: init a project, sign in, have your agent write a page, push it, and pull it from another machine.
- [What Contexo is](https://docs.contexo.live/start/what-is-contexo/): A per-project knowledge base your coding agent reads and writes over MCP, versioned in git and shared with the rest of the team.

## Guides

Task-shaped walkthroughs.

- [The daily flow](https://docs.contexo.live/guides/daily-flow/): Two developers, one knowledge base: how a session's reasoning becomes a page the other person's agent reads before it touches the code.
- [Drift and conflicts](https://docs.contexo.live/guides/drift-and-conflicts/): How Contexo warns an agent that a page moved, what the 409 merge loop looks like, and how to reconcile by hand when no agent is driving.
- [Seed a knowledge base from code](https://docs.contexo.live/guides/generate/): When a project has no docs to migrate, ctx generate maps the codebase with Graphify and has your agent verify each slice against real source before writing pages.
- [Migrate an existing knowledge base](https://docs.contexo.live/guides/migrate/): Point ctx migrate at a wiki, a docs/ tree, ADRs or agent instruction files, and have your agent reformat what you pick into Contexo pages.
- [How a page evolved](https://docs.contexo.live/guides/page-evolution/): Reconstructing a page's trajectory with ctx history, ctx diff and ctx evolution — and knowing which of the three answers your question.
- [Self-hosting the server](https://docs.contexo.live/guides/self-hosting/): Run your own Contexo server with Docker or a plain binary: the complete environment reference, where state lives, backups, reverse proxy, and the identity trade-off.
- [Working as a team](https://docs.contexo.live/guides/teams/): Invite keys, owner and member roles, removing people, and what the activity feed does — and doesn't — record about agents.
- [Updating and uninstalling](https://docs.contexo.live/guides/updating/): How ctx update verifies a release before replacing itself, what ctx detach removes, and how to take Contexo off a machine completely.

## CLI reference

Every ctx command, its flags and worked examples.

- [CLI reference](https://docs.contexo.live/cli/): Every Contexo command, grouped by what you are trying to do.
- [ctx activity](https://docs.contexo.live/cli/activity/): The repo activity feed — who pushed, who pulled, and when.
- [ctx capture](https://docs.contexo.live/cli/capture/): Inspect the local per-session turn buffer that the agent hooks write into.
- [ctx detach](https://docs.contexo.live/cli/detach/): Reverse ctx init — remove the MCP entries, hooks and .gitignore line, and by default delete .contexo/ itself.
- [ctx diff](https://docs.contexo.live/cli/diff/): Section-aware diff between two versions of a page — by frontmatter field and by ## section, not by line.
- [ctx evolution](https://docs.contexo.live/cli/evolution/): Every commit that touched a page plus what each one changed, in a single round-trip.
- [ctx generate](https://docs.contexo.live/cli/generate/): Seed a knowledge base from source code: run Graphify over the codebase and stage the subsystems and components you pick.
- [Global flags and environment](https://docs.contexo.live/cli/global-flags/): The flags every ctx command accepts, and every environment variable ctx reads — with defaults, accepted values and effects.
- [ctx history](https://docs.contexo.live/cli/history/): List every commit that touched one page, newest first.
- [ctx hooks](https://docs.contexo.live/cli/hooks/): Install the per-turn capture hook into Claude Code, Codex, and Cursor.
- [ctx init](https://docs.contexo.live/cli/init/): Create .contexo/, wire the MCP server into your agents, and install the capture hooks — offline, idempotent, one command.
- [ctx invite](https://docs.contexo.live/cli/invite/): Mint, list and revoke the ctxi_ keys that let teammates join a repo.
- [ctx join](https://docs.contexo.live/cli/join/): Redeem a ctxi_ invite key to become a member of an existing repo and point this project at it.
- [ctx log](https://docs.contexo.live/cli/log/): The server's commit timeline for this repo — who changed what, when.
- [ctx login](https://docs.contexo.live/cli/login/): Sign in to a Contexo server — browser flow, pasted token, --token, or a legacy self-hosted key — and see what you are signed in as.
- [ctx mcp](https://docs.contexo.live/cli/mcp/): Run the stdio MCP server your agent talks to, and wire it into Claude Code, Cursor, and Codex.
- [ctx members](https://docs.contexo.live/cli/members/): List who can read and write the current repo, and remove people who shouldn't.
- [ctx migrate](https://docs.contexo.live/cli/migrate/): Find the docs, wikis and agent instruction files a project already has, and stage the ones you pick for your agent to import.
- [ctx pull](https://docs.contexo.live/cli/pull/): Fetch pages committed on the server into .contexo/ and rebuild the local index.
- [ctx push](https://docs.contexo.live/cli/push/): Send local .contexo pages to the team server — with a preview of what changes before anything leaves your machine.
- [ctx remote](https://docs.contexo.live/cli/remote/): Read and edit the two settings that decide where this project syncs: the server URL and the repo id.
- [ctx status](https://docs.contexo.live/cli/status/): Where this project stands: config, auth, page counts, and which pages moved on the server.
- [ctx update](https://docs.contexo.live/cli/update/): Check GitHub for a newer ctx release and replace the running binary with the verified build for your platform.
- [ctx version](https://docs.contexo.live/cli/version/): Print the build identity of the ctx binary — version, commit and build date — or just the number.

## MCP reference

Every tool, resource and directive an agent sees.

- [MCP reference](https://docs.contexo.live/mcp/): The stdio MCP server behind ctx mcp: ten tools, five resources, and how each agent is wired to it.
- [ctx_capture_session](https://docs.contexo.live/mcp/ctx-capture-session/): Hands the agent a source-page template plus this session's capture buffer. Writes nothing, pushes nothing — the agent still has to distill.
- [ctx_diff](https://docs.contexo.live/mcp/ctx-diff/): A section-aware diff between two versions of a page: frontmatter as old→new per field, each ## section added, removed, modified, unchanged, or renamed.
- [ctx_evolution](https://docs.contexo.live/mcp/ctx-evolution/): Every commit that touched a page, each paired with its own section diff — the whole trajectory in one round-trip instead of history plus N diffs.
- [ctx_generate](https://docs.contexo.live/mcp/ctx-generate/): Map a codebase into a catalog of subsystems and components the agent verifies against source.
- [ctx_history](https://docs.contexo.live/mcp/ctx-history/): Every commit that touched one page, newest first — the cheapest way for an agent to see a page's trajectory before it edits.
- [ctx_migrate](https://docs.contexo.live/mcp/ctx-migrate/): Discover an existing knowledge base and hand the agent a numbered catalog to distill.
- [ctx_pull](https://docs.contexo.live/mcp/ctx-pull/): Fetch the team's pages into the local .contexo/ — incremental by default, and what lands is data, not instructions.
- [ctx_push](https://docs.contexo.live/mcp/ctx-push/): Push local pages to the team server — including the distill handshake and the three-way merge directive.
- [ctx_status](https://docs.contexo.live/mcp/ctx-status/): An offline snapshot of the local .contexo/: server, repo, auth, page counts, last pull, and pending capture buffers.
- [ctx_write_page](https://docs.contexo.live/mcp/ctx-write-page/): The agent's only writer: creates a page in .contexo/ with valid ctx.page.v1 frontmatter.
- [Agent directives](https://docs.contexo.live/mcp/directives/): Every instruction block Contexo returns, what triggers it, and how the loop ends.
- [Resources](https://docs.contexo.live/mcp/resources/): The five read-only ctx:// URIs an agent can load, what each returns, and when to load it.

## Elsewhere

- [Contexo home](https://contexo.live): what Contexo is, how it works, pricing.
- [Source](https://github.com/sugihAF/contexo): the Go CLI and server.
- [Full docs as one file](https://docs.contexo.live/llms-full.txt): every page's Markdown concatenated.