ccstack

Local-first control surface for inspecting and managing Claude Code configuration across global (~/.claude) and project (.claude/) scopes.

Project status: the configuration-management surface is complete. Remaining ideas and intentionally deferred work are tracked in docs/future-scope.md; the current implementation audit is in docs/completion-review.md.

Current capabilities

• Switch between global and remembered project scopes, with each view restricted to its own configuration.
• Manage skills, plugins, commands, agents, MCP servers, LSP servers, monitors, channels, hooks, permissions, memory, model settings, output styles, statusline, themes, keybindings, general settings, marketplaces, and worktree configuration.
• Review every supported mutation as a file diff before applying it.
• Inspect effective values, scope provenance, plugin ownership, validation findings, and next-session or reload requirements.
• Read and edit Markdown with rendered preview, frontmatter presentation, syntax highlighting, wrapping controls, and keyboard navigation.
• Select a project with Finder on macOS or paste an absolute path on any supported platform.

Requirements

• Bun
• A Claude Code configuration to manage (ccstack also works with an empty config directory)

The native Finder picker is macOS-only. Manual project-path selection remains available on other platforms.

Tagged releases are also published through Homebrew:

brew install amitray007/tap/ccstack

Run locally

For normal use, start the app through its CLI. It builds the current web UI, starts one localhost-only service, and opens the browser:

bun install
bun run cli

Useful options:

bun run cli -- --no-open
bun run cli -- --claude-dir ./fixtures/golden-tree/user
bun run cli -- --port 43118

The command returns after the background service is ready. A second invocation for the same Claude configuration focuses the already-running instance.

To expose the source-linked command on Bun's PATH:

bun run build:web
bun link
ccstack

The linked command starts in the background, so it does not occupy the terminal:

ccstack
ccstack status
ccstack doctor
ccstack stop

Use ccstack serve when you want the service attached to the current terminal.

For UI development with Vite hot reload:

bun install
bun run dev

Open http://localhost:5273. To develop against a fixture instead of your real Claude Code configuration:

CLAUDE_CONFIG_DIR=./fixtures/golden-tree/user bun run dev

Build and verify

bun run build
bun test
bun run typecheck
bun run lint

bun run build writes a standalone executable to dist/ccstack. The Vite UI is embedded in that executable, so it can be launched from any working directory without a separate web bundle or Bun installation:

./dist/ccstack

Local-first and safety

ccstack runs on localhost and treats Claude Code's existing files as the source of truth. It does not require a hosted service. Writes use validated diff/apply operations and are restricted to the relevant Claude Code configuration paths, but they can still change your live setup. Use CLAUDE_CONFIG_DIR with a fixture or backup when evaluating write operations.

For current implementation status, start with docs/completion-review.md. For the product contract and design constraints, see docs/spec.md, docs/decisions.md, and DESIGN.md. Maintainer release setup is documented in docs/releasing.md.

Contributing and security

Issues and pull requests are welcome. Read CONTRIBUTING.md before making a change and follow the CODE_OF_CONDUCT.md when participating.

Do not report vulnerabilities in a public issue. Follow SECURITY.md for private reporting guidance. Published changes are recorded in CHANGELOG.md.

License

ccstack is available under the MIT License.