Name: CodeSpeak
Author: CodeSpeak

Extract specifications from existing code — either for specific paths you hand in, or for a whole project via an interactive modularization wizard.

Synopsis

codespeak takeover [paths...] [-o OUTPUT] [-f] [--cc-context | --no-cc-context] [--cc-session-dir DIR] [--cc-original-root PATH] [--no-interactive]

Description

Reads existing source code and generates spec files that capture its behavior. Generated specs are registered in codespeak.json, and from that point on you maintain the specs instead of the code.

Extracted specs capture what the code does — its purpose, interfaces, and behavior — without reproducing the code itself.

If no CodeSpeak project exists but the directory is inside a Git repo, takeover auto-initializes the project first.

Takeover modes

codespeak takeover runs in one of two modes depending on whether you pass paths.

Path-based

codespeak takeover src/module_a/ src/module_b.py

When paths are given, takeover produces a single spec file covering exactly those files. This is the right mode when you already know the module boundary you want to extract.

Output file defaults to <first-path-stem>.cs.md next to the source; override with -o.
-f overwrites an existing spec at the output path.

Module-based (modularization wizard)

codespeak takeover

When invoked with no paths, takeover analyzes the whole project, proposes a modular decomposition, and opens an interactive modularization wizard in your browser. You inspect the proposed modules, refine the structure (split, merge, rearrange responsibilities), and pick which modules to hand over. Confirming the plan writes one spec per selected module under specs/ and wires up their imports automatically.

Module metadata is recorded in .codespeak/ignored/modules.json so the wizard can resume where you left off.

-o is only valid in path-based mode — in module-based mode, output paths are derived from module names.

Claude Code integration

By default, takeover reads your recent Claude Code session history to understand the intent behind the code. This produces richer specs that capture not just what the code does, but why it was written that way. Pass --no-cc-context to opt out of this enrichment.

On first use, CodeSpeak asks permission to read sessions:

CodeSpeak can read your Claude Code session history to better understand
the intent behind your code. Is this fine?

[Y] Allow  [N] Not now  [D] No, never

Your choice is recorded per-project in ~/.codespeak/preferences.json.

During the build, CodeSpeak shows which sessions and prompts it analyzed:

✓ Extract specification (2m 34s)
╰─ ✓ Analyze Claude Code sessions (0.0s) - 24 sessions, 150 prompts:
           "Implement @ideation/blog.md  Plan first",
           "react-dom-client.development.js:5530 Uncaught Error: Hydration failed because...",
           and 147 more
╰─ ✓ Write specification (2m 34s)

--cc-context / --no-cc-context explicitly force-enable or disable this enrichment, overriding the saved per-project preference. --cc-session-dir and --cc-original-root are for advanced cases where the session history is on a different machine or at a different path.

Flags

Flag	Description
`paths`	Files or directories to extract a specification from. If omitted, opens the interactive modularization wizard
`-o`, `--output OUTPUT`	Output file path for the specification (relative to project root or absolute, must be under project root). Only valid when paths are given
`-f`, `--force`	Overwrite existing specification file if it exists
`--cc-context` / `--no-cc-context`	Read Claude Code session history to enrich spec extraction with original intent
`--cc-session-dir DIR`	Path to a Claude Code session directory (overrides automatic discovery and skips consent)
`--cc-original-root PATH`	Project root on the original machine (used with `--cc-session-dir` to remap foreign paths)
`--no-interactive`	Run in non-interactive mode without real-time progress updates

Error messages

Error	Cause	Resolution
Anthropic API Key not found	No API key configured	Set the `ANTHROPIC_API_KEY` environment variable or run through the interactive setup
{path} does not belong to a CodeSpeak project	No `codespeak.json` found	Run `codespeak init` first
Specification file '{path}' already exists	Output spec file already exists	Use `-f` to overwrite, or specify a different output with `-o`
Output path can not be a directory	`-o` points to a directory, not a file	Provide a file path
No .codespeak/modules.json found	Running `takeover` without paths and no module map exists	Run `/arch-explore` in Claude Code to generate the module map, or provide explicit paths: `codespeak takeover <paths>`
No modules selected for takeover in .codespeak/modules.json	Module map exists but no modules are marked for takeover	Run `/arch-explore` in Claude Code and select modules to take over
--output cannot be used with module-based takeover (no paths)	`-o` flag used without explicit paths	Either provide explicit paths with `-o`, or omit `-o` for module-based takeover
--cc-original-root requires --cc-session-dir	Missing session dir with original root	Also specify `--cc-session-dir`
--output cannot be used with module-based takeover (no paths)	`--output` passed without any paths, so takeover runs in module-based mode and produces multiple specs	Either pass the path(s) you want extracted into a single spec, or drop `--output` to let the modularization wizard place the generated specs

codespeak takeover