[![npm version](https://img.shields.io/npm/v/gsd-munch)](https://www.npmjs.com/package/gsd-munch)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/node/v/gsd-munch)](https://nodejs.org)

# gsd-munch

GSD workflow orchestration + tree-sitter code indexing for Claude Code.

## Quickstart

```sh
npm install -g gsd-munch
```

The postinstall script runs automatically and:

- Provisions a Python runtime via [uv](https://github.com/astral-sh/uv) (no system Python required)
- Installs the jCodeMunch MCP server into an isolated virtualenv
- Registers the MCP server with Claude Code
- Deploys GSD workflow commands (`/gm:*`) to your Claude Code installation

After install, restart Claude Code and use `/gm:help` to see all available commands.

## Recommended Usage

GSD is designed for frictionless automation. Run Claude Code with:

```sh
claude --dangerously-skip-permissions
```

This allows GSD agents to execute plans, run builds, and commit code without repeated permission prompts. Without it, each tool call requires manual approval, which interrupts the autonomous workflow GSD is built for.

## GSD Workflow Commands

All commands are available as `/gm:*` slash commands inside Claude Code.

### Project Setup

| Command | Description |
|---------|-------------|
| `/gm:new-project` | Initialize a new GSD project — creates `.planning/` structure, maps codebase, and indexes for symbol retrieval |
| `/gm:map-codebase` | Re-map and re-index the codebase, refreshing the symbol database and project context |

### Planning

| Command | Description |
|---------|-------------|
| `/gm:discuss-phase` | Open-ended discussion to clarify phase goals before committing to a plan |
| `/gm:plan-phase` | Generate a structured execution plan for a phase, with per-task breakdowns |
| `/gm:research-phase` | Spawn a research agent to investigate technical decisions before planning |

### Execution

| Command | Description |
|---------|-------------|
| `/gm:execute-phase` | Execute a phase plan — runs tasks atomically with per-task commits |
| `/gm:verify-work` | Run UAT for a phase — presents each deliverable for confirmation, logs issues |
| `/gm:quick` | Run a quick one-off task without full phase scaffolding |

### Session Management

| Command | Description |
|---------|-------------|
| `/gm:pause-work` | Snapshot current session state to `.planning/STATE.md` for safe context handoff |
| `/gm:resume-work` | Resume from a paused session — restores context and picks up where left off |
| `/gm:progress` | Display current project progress, phase status, and recent decisions |

### Settings and Debugging

| Command | Description |
|---------|-------------|
| `/gm:settings` | Configure GSD behaviour (model profiles, parallelization, auto-chain) |
| `/gm:help` | Show all available commands with brief descriptions |
| `/gm:debug` | Diagnose GSD installation issues — checks Python, MCP, assets, and workflows |

### Phase Management

| Command | Description |
|---------|-------------|
| `/gm:add-phase` | Append a new phase to the project roadmap |
| `/gm:insert-phase` | Insert a phase at a specific position in the roadmap |
| `/gm:remove-phase` | Remove a phase from the roadmap |

### Milestone Management

| Command | Description |
|---------|-------------|
| `/gm:audit-milestone` | Review all deliverables for a milestone against acceptance criteria |
| `/gm:complete-milestone` | Mark a milestone complete and generate a completion report |
| `/gm:new-milestone` | Define a new milestone with goals, phases, and success criteria |

## Code Indexing

gsd-munch bundles the [jCodeMunch MCP](https://github.com/jgravelle/jcodemunch-mcp) server, providing tree-sitter AST parsing for 14+ languages. The MCP server is registered automatically with Claude Code on install.

Available MCP tools:

| Tool | Description |
|------|-------------|
| `index_folder` | Index a directory — builds symbol database for all supported files |
| `index_repo` | Index an entire repository with git-aware file selection |
| `get_repo_outline` | Get a high-level outline of all symbols in the indexed repository |
| `get_file_outline` | Get the symbol outline for a single file |
| `get_symbol` | Retrieve the exact source of a named symbol (function, class, method) |
| `search_symbols` | Search symbols by name pattern across the indexed codebase |
| `search_text` | Full-text search across indexed files |

The codebase is automatically re-indexed on project initialization and after each git commit (via a post-commit hook installed by `/gm:new-project`).

Using `get_symbol` or `get_file_outline` instead of reading whole files reduces the tokens required for each agent task — particularly useful in multi-file refactors or when navigating large codebases.

## Token Savings

At phase completion, `/gm:verify-work` estimates the tokens saved via symbol retrieval compared to reading whole files. If symbol retrievals occurred during the phase, a savings summary line is appended to the UAT output and recorded in `.planning/STATE.md` under Performance Metrics.

Example output:

```
Saved ~14k tokens via symbol retrieval this phase
```

This is an estimate based on a chars/4 heuristic and is informational only — it never blocks or errors.

## Attribution

gsd-munch builds on two upstream projects:

- **get-shit-done** by GSD Team / TACHES — structured project planning and execution workflows for Claude Code.
  Repository: [gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done) — MIT License
- **jcodemunch-mcp** by J. Gravelle — tree-sitter AST parsing and symbol retrieval via the MCP protocol.
  Repository: [jgravelle/jcodemunch-mcp](https://github.com/jgravelle/jcodemunch-mcp) — Custom non-commercial license

See [NOTICES](./NOTICES) for pinned upstream versions and full license details.

## License

MIT — see [LICENSE](./LICENSE).

Third-party attribution and license details for upstream projects are in [NOTICES](./NOTICES).