Metadata-Version: 2.4
Name: codewalker
Version: 0.1.0
Summary: Deterministic, offline static-analysis tool that carves any git repo into units and extracts per-unit factual signals (LLM call sites, regex parse sites, frameworks, integrations, Taxi schemas) with file:line evidence. Exposes analysis as an MCP server.
Project-URL: Homepage, https://github.com/jhammant/codewalker
Project-URL: Repository, https://github.com/jhammant/codewalker
Project-URL: Issues, https://github.com/jhammant/codewalker/issues
Project-URL: Changelog, https://github.com/jhammant/codewalker/blob/main/CHANGELOG.md
Author: CodeWalker contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agents,code-analysis,code-intelligence,llm,mcp,model-context-protocol,static-analysis,taxi,taxilang,tree-sitter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: tree-sitter-language-pack>=0.7
Requires-Dist: tree-sitter>=0.23
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# CodeWalker

**Deterministic, offline code exploration — ground truth for AI agents.**
CodeWalker carves any git repo into navigable *units* and extracts factual
signals about what the code **calls, imports and integrates** — LLM call sites
(provider + model), frameworks, integrations, prompts, git recency, Taxi schemas
— **each with `file:line` evidence, no LLM, no code execution.**

It's the deterministic half of a two-step idea:

> **① CodeWalker explores** the repo → facts, every one a `file:line`.
> **② your LLM reads those facts** and maps the codebase → grounded, cited, not guessing.

It exposes its analysis as an **MCP server** (so Claude Code and any agent use it
as ground truth) plus a local web explorer.

![CodeWalker — explore the code, ground the LLM](docs/demo.gif)

## Philosophy

- **Signals are ground truth**, derived from AST / regex / filesystem / git —
  never an LLM guess. Classification is a navigational heuristic; the evidence
  is the truth.
- **Every signal carries evidence**: a `file:line` you can jump to. No claim
  without a location.
- **Cheap deterministic substrate**: any LLM "judgment" runs *on top* of this
  output, not inside it.
- **Generalize**: nothing is hardcoded to a repo, company or domain — every
  target is configuration.
- **First-class [Taxi](https://taxilang.org)**: `.taxi` schemas are parsed into
  a semantic-type usage graph (which models/services consume which semantic
  types).

## What it extracts (per unit)

Size & languages, models referenced (`gpt-*`, `claude-*`, …), LLM call sites
(provider + model + via + `file:line`), regex parse sites, frameworks,
integrations, an AST-derived call graph (imports / subprocess / http / aws / db
/ tools / a2a / mcp), prompts + a request table, output formats, key deps, git
recency, a heuristic classification + status, a deterministic plain-English
summary, an architecture graph, and a full Taxi schema where present.

## Run it in 30 seconds

No install needed — point [`uv`](https://docs.astral.sh/uv/) at the repo:

```bash
# explore any repo in your browser (clones it if you pass a git URL):
uvx --from "git+https://github.com/jhammant/codewalker" codewalker web /path/to/repo

# or run the MCP server so Claude Code can use it:
uvx --from "git+https://github.com/jhammant/codewalker" codewalker mcp /path/to/repo
```

## Install

```bash
# from the repo (works today):
pip install "git+https://github.com/jhammant/codewalker"

# from PyPI (once published — see .github/workflows/release.yml):
pip install codewalker          # or:  uv tool install codewalker

# from source (for development):
git clone https://github.com/jhammant/codewalker && cd codewalker
uv venv --python 3.13 .venv && uv pip install -e ".[dev]" && pytest
```

Requires Python 3.10+. tree-sitter grammars (for deep AST analysis) install
automatically via `tree-sitter-language-pack`.

## Use

```bash
# Analyze one repo (caches OUTSIDE the repo, in ~/.cache/codewalker)
codewalker analyze /path/to/repo
codewalker analyze /path/to/repo --reindex     # force rebuild

# Estate report / map
codewalker report /path/to/repo
codewalker map /path/to/repo --group-by package

# Taxi schema (global merged "router" view, or a single unit's)
codewalker taxi /path/to/repo
codewalker taxi /path/to/repo <unit_id>

# Agent Pack — a deterministic markdown briefing for a coding agent
codewalker pack /path/to/repo                  # whole repo
codewalker pack /path/to/repo <unit_id>        # one unit
codewalker pack /path/to/repo --out PACK.md

# Run the MCP server over stdio (primary interface)
codewalker mcp /path/to/repo

# Web explorer (live API at http://localhost:8765) — single repo OR a workspace
codewalker web /path/to/repo
codewalker web ~/dev --max-repos 40            # a whole folder of repos

# Bake a shareable offline static bundle
codewalker bake /path/to/repo --out ./bundle
```

### Explore a whole developer's work (a "workspace")

Point CodeWalker at a directory of repos (or a GitHub user) and get a portfolio —
every child git repo analyzed, with cross-repo aggregates and a per-repo +
portfolio Agent Pack:

```bash
codewalker explore ~/dev                       # local folder of repos (offline)
codewalker explore ~/dev --max-repos 20
codewalker explore ~/dev --pack                # portfolio Agent Pack (markdown)
codewalker explore gh:someuser                 # clone+analyze a user's repos (needs the gh CLI)
```

In the browser you can also **point at a new repo on the fly** — the topbar's
*Open* box takes a local path or a git URL (cloned + cached), no restart needed.

### Screenshots

A unit's deterministic **Explained** view (every signal a `file:line`) and the
**Taxi** semantic-type graph:

![CodeWalker web explorer — a unit explained, every signal a file:line](docs/explorer-explained.png)
![CodeWalker web explorer — the Taxi semantic-type usage graph](docs/explorer-taxi.png)

## MCP tools

`analyze`, `explore` (workspace portfolio), `list_units`, `get_unit`, `search`,
`read_file`, `report`, `map`, `taxi_schema`, `agent_pack`, `tech_profile` — plus
read-only resources `unit://<id>`, `report://estate`, `taxi://<unit_id>`. Tool
descriptions state explicitly that results are deterministic static analysis with
`file:line` evidence — facts to verify, not prose to trust.

The **Agent Pack** (`agent_pack` / `codewalker pack`) is the deep, deterministic
counterpart to a GitHub-metadata "agent pack": a concise markdown briefing of
what the code actually does (units, what each calls, the Taxi semantic-type web,
frameworks), every claim backed by `file:line`.

## The LLM-analysis layer (run it via Claude Code or any agent)

CodeWalker is the deterministic *substrate*; the **judgment** (audits, reviews,
dossiers) is an LLM pass **on top**. Three ways to drive it:

- **Claude Code plugin** (`plugin/`): bundles the MCP server + slash-commands and
  a code-analysis skill. Install:
  ```text
  /plugin marketplace add jhammant/codewalker
  /plugin install codewalker
  /cw-audit          # audit · /cw-explain <unit> · /cw-taxi-review · /cw-dossier <dir|gh:org>
  ```
- **RECIPES.md**: copy-paste analysis prompts for any MCP-capable agent (BYO).
- **Agent SDK** (`examples/agent_sdk_audit.py`): a headless Python harness that
  runs CodeWalker + an LLM audit pass — CI/cron friendly.

Each keeps the contract: facts come from CodeWalker (with `file:line`), the model
adds judgment and **verifies before concluding**.

## Coverage honesty

Languages with a tree-sitter grammar (Python, JS/TS, Go, Java, Rust, Ruby, C#,
Kotlin, Scala, Shell, Rego, SQL, HCL) get the deep AST signals; other languages
are line-counted and regex-scanned only, and each unit summary says so.

## Contributing & license

Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) (keep it
deterministic, offline, evidence-backed). New detection patterns are usually just
a data edit in `config.py`. Licensed **MIT** (see [LICENSE](LICENSE)).
