cframe

A CLI tool for managing Claude-based projects.

Structure your Claude Code projects with phase-based planning, progress tracking, and archival so long-running projects stay organized across sessions.

Installation

Linux / macOS

./install.sh

Add to PATH if needed:

export PATH="$HOME/.local/bin:$PATH"

Windows

Double-click install.bat or run from command line:

install.bat

Or directly in PowerShell:

.\install.ps1

Requires Python 3 installed and in PATH.

Note: macOS and Windows support is untested. Please open an issue if you encounter problems.

Usage

Create a new project directory

cframe init my-project
cframe init my-project --design --systems

Add to existing project directory

# From inside
cframe init

# From outside
cframe init path/to/existing-project

Add extensions

cframe add --deploy

List available extensions

cframe list

Show project status

cframe status

Archive a file

Archives the file and resets it from the base template. Run from a project root or inside .claude/.

cframe archive phase      # current-phase.md -> archive/phases/phase-#.md
cframe archive progress   # progress.md      -> archive/progress/progress-#.md
cframe archive prompt     # prompt.md        -> archive/prompts/prompt-#.md
cframe archive overview   # overview.md      -> archive/overviews/overview-#.md

Suggested Workflow

1. Run cframe init and update .claude/overview.md with a project summary and deliverables
2. Run Claude in plan mode and collaborate to define phases and high-level tasks in overview
3. Plan the first current-phase using overview as reference; include details, edge cases, and granular tasks
4. Optionally add extensions (cframe add --deploy) and populate their md files with specs
5. Iterate until current-phase is complete
6. Repeat for each phase until the project is finalized

Tip: Some extensions are self-updating. For example, --deploy updates automatically when Claude recognizes deployment-relevant steps.

Extensions

Extension	Description
--design	UI/UX design planning and documentation
--deploy	Deployment steps and documentation
--systems	System architecture and infrastructure

Project Structure

After cframe init, your project contains:

.claude/
  .cframe/           # cframe metadata
    extensions.json  # Installed extensions
  CLAUDE.md          # Claude instructions
  extensions.json    # Installed extensions
  overview.md        # Project roadmap
  current-phase.md   # Active work
  progress.md        # Progress log
  prompt.md          # Large prompt input
  archive/           # Historical records

License

MIT