codespeak takeover
Extract a specification from existing code.
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 a spec that captures its behavior. The generated spec is registered in codespeak.json, and from that point on, you maintain the spec instead of the code.
The extracted spec captures 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.
Flags
| Flag | Description |
|---|---|
paths | Files or directories to extract a specification from |
-o, --output OUTPUT | Output file path for the specification (relative to project root or absolute, must be under project root) |
-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 |
Note: --intent and --raw-intent flags exist for advanced use — --intent extracts a spec from Claude Code session prompts (user intent) instead of code, and --raw-intent saves the raw session prompts directly without LLM processing.
Claude Code integration
When --cc-context is enabled, 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.
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-session-dir and --cc-original-root are for advanced use cases where the session history is on a different machine or at a different path.
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 |
| --cc-original-root requires --cc-session-dir | Missing session dir with original root | Also specify --cc-session-dir |
| --no-cc-context conflicts with --intent | Incompatible flags | Remove one of the conflicting flags |
See also
- Convert Existing Code to Specs tutorial — step-by-step walkthrough
- Spec-Driven Code Evolution — the philosophy behind maintaining specs instead of code