Metadata-Version: 2.4
Name: codemap-agents
Version: 0.5.1
Summary: Auto-generated, budget-bounded codebase maps inside AGENTS.md — spec + stdlib-only reference generator with git-hook, CI, watch, and MCP integrations
Author: Mehmet Apaydın
License: MIT
Project-URL: Homepage, https://github.com/xenitV1/codemap
Project-URL: Repository, https://github.com/xenitV1/codemap
Keywords: agents,AGENTS.md,codebase-map,mcp,llm,context
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# codemap

**Auto-generated, budget-bounded codebase maps inside AGENTS.md — so coding
agents stop re-exploring your repo at the start of every session.**

Coding agents don't fail at *finding* code; they fail at knowing the *shape*
of a system in the first minutes of a session. Codemap keeps a small
(≤ 2,000-token) machine-generated map inside [`AGENTS.md`](https://agents.md/)
— the context file agents already read — and keeps it provably fresh.

- **Compass, not encyclopedia** — three layers under a hard token budget:
  `L0` annotated directory layout · `L1` key files ranked by import graph ·
  `L2` public signatures.
- **Freshness contract** — deterministic output, `check` with CI-friendly
  exit codes, a pre-commit hook so the map travels in the same commit as the
  change, and an MCP server that refreshes the map at session start.
- **Zero dependencies** — single stdlib-only Python package (≥ 3.9), 40+
  languages, local-only, no network, never fails on unknown file types.
- **A format, not just a tool** — the block layout and freshness rules are a
  spec ([codemap-spec.md](codemap-spec.md)); any generator can implement it.

## Install

```bash
pipx install codemap-agents      # PyPI (or: uv tool install codemap-agents)
pipx install git+https://github.com/xenitV1/codemap   # bleeding edge
# or, from a clone: python3 bin/codemap ... / pipx install .
```

The installed command is `codemap` in all cases.

### Always-latest, npx-style (no install)

For MCP configs that should track the newest release automatically — the
Python equivalent of `npx some-server@latest`:

```bash
uvx codemap-agents@latest mcp --no-cache                                # PyPI
uvx --refresh --from git+https://github.com/xenitV1/codemap codemap mcp --no-cache  # git HEAD
```

Trade-off: the launcher checks for updates at every server start (a few
seconds cold). Pin a version or use `pipx install` if session startup
latency matters more than freshness.

## Quickstart

```bash
cd your-project
codemap update        # writes the map block into ./AGENTS.md (creates skeleton if missing)
codemap check         # exit 0 fresh / 1 drift / 2 no map — wire this into CI
codemap install --ci  # pre-commit hook + GitHub Actions freshness gate
```

Everything between `<!-- codemap:begin -->` and `<!-- codemap:end -->` is
machine-owned; everything outside is yours (architecture notes, conventions,
warnings — the parts only humans can write).

Exclude vendored or irrelevant directories with gitignore-like globs in a
repo-local `.codemapignore` (travels with the repo, CI sees it) or a
user-global `~/.codemapignore` (every repo on your machine).

## Automatic mode (MCP)

`codemap mcp` is a stdio MCP server. Registered once at user scope, it starts
automatically with every agent session, refreshes AGENTS.md for the project it
opens in (git repos only), and exposes on-demand tools: `codemap` (return a
fresh map without writing files), `codemap_update`, `codemap_check`.

```bash
# Claude Code
claude mcp add --scope user codemap -- codemap mcp --no-cache

# Codex CLI — ~/.codex/config.toml
[mcp_servers.codemap]
command = "codemap"
args = ["mcp", "--no-cache"]

# opencode — ~/.config/opencode/opencode.json
"mcp": { "codemap": { "enabled": true, "type": "local",
                      "command": ["codemap", "mcp", "--no-cache"] } }
```

Any other MCP client: stdio transport, command `codemap mcp --no-cache`.

## Agent skill

```bash
codemap skill   # installs SKILL.md into ~/.agents/skills/codemap and ~/.claude/skills/codemap
```

Skill-aware agents (Claude Code, Codex, …) then know when and how to use the
tool without extra prompting.

## All commands

| Command | What it does |
|---|---|
| `codemap update` | (Re)generate the map block in `./AGENTS.md` |
| `codemap check` | Freshness: exit `0` fresh / `1` drift / `2` missing |
| `codemap print` | Write the block to stdout, touch nothing |
| `codemap install [--ci]` | Pre-commit hook (+ CI workflow) for this repo |
| `codemap watch` | Regenerate on every source change while you work |
| `codemap mcp` | MCP stdio server with session-start auto-refresh |
| `codemap skill` | Install the agent SKILL.md |

Options: `--root PATH` · `--file AGENTS.md` · `--budget 2000` · `--no-cache` ·
`--quiet` · `--interval N` · `--include-ext .foo,.bar`

## How it works

A full tree walk every run (adds/deletes reflected by construction), regex
import/symbol extraction per language, import-graph PageRank for L1 ranking,
and budget-driven degradation (drop L2 first, then L1, then collapse L0).
Output is deterministic — same tree, same bytes — which is what makes `check`
and reviewable map diffs possible. An incremental content-hash cache makes
warm runs fast and is semantically invisible.

Measured: ~130-file repo ≈ 0.2 s · ~900-file repo ≈ 0.4 s cold.

## Tests

```bash
python3 -m unittest discover -s tests -v
```

## License

[MIT](LICENSE)
