Adeptly

Plan-first companion for Claude Code. Describe what you want to build — Adeptly drafts the full plan and bakes the right Claude Code features (subagents, skills, hooks, /security-review, MCP, plan mode, auto-memory) into each section. Then run the plan as a crew. Runs locally on your machine, uses your existing Claude Code subscription, never sends your code anywhere else.

npx adeptly

That's it. Opens at http://localhost:3000, reads plans from docs/plans/ in your current directory, and uses your local claude CLI for everything AI-powered.

🔒 Your code never leaves your machine

No SaaS backend, no API key, no telemetry, no analytics, no account. Adeptly is a thin GUI on top of your claude CLI. If you trust Claude Code, Adeptly adds zero new trust surface.

Why Adeptly exists

If you're using Claude Code today, you're probably using maybe 15% of it. Plan mode, subagents, skills, hooks, MCP servers, auto-memory — most users never discover them. And when 3–5 developers share a repo and all use Claude to commit, nobody knows what anyone else is planning until the PR lands.

Adeptly solves both:

• Discover the features you're paying for. Every plan gets a recipe: which subagents to spawn, which skills to invoke, which hooks to wire, expected turn count. Feature names are underlined inline in the rendered plan with hover explanations — you learn what to use by reading your own plans.
• One plan-first workflow for your whole team. Plans live as markdown in docs/plans/. Every dev on the team sees the same plans, the same approval state. Git is the sync layer. No backend to manage.

The core of Adeptly stays the same: it's the only tool that surfaces every Claude Code feature — subagents, skills, hooks, MCP, plan mode, /security-review, auto-memory — and tells you exactly where and why to use each one, inline in your own plans. Nobody else explains Claude Code like this. The Crew below just lets you watch those features run.

🆕 New in v0.8 — team-scale, whole-picture

• Session handoff — Claude Code sessions can't talk to each other live. Leave a handoff note (what's done, what's next, branch, plan) and Copy resume prompt into a fresh claude session to continue without rebuilding context. The bridge sessions can't make themselves.
• Whole-account usage — the Usage panel now has a Whole account view: it parses every Claude Code transcript under ~/.claude to show machine-wide token usage, estimated cost, cache-hit, by-model, and a daily-cost sparkline — not just Adeptly's own calls. (Tokens exact; cost estimated from public rates. Still 100% local.)
• Crew run history + re-run — browse every past crew run for a plan (mode, pass count, time, cost, PR) and re-run any of them in one click.
• Remote / tunnel — adeptly --tunnel exposes the app via a Cloudflare quick-tunnel (with a loud "anyone with this URL can drive your claude" warning), plus clearer --host security guidance.
• Parallel crew stages — Reviewer and Security review the diff concurrently (both are advisory and independent), so live runs finish sooner.

🆕 New in v0.7 — see your usage, spend less

Adeptly now helps you get more Claude Code for less:

• Coverage — every plan gets a score: how many of Claude Code's 30+ features is this plan actually using? Plus the specific high-value ones it's missing (and why), one click to add each. This is the core pitch made measurable.
• Token Hygiene (Savings) — an efficiency score for the plan against the money-saving Claude habits: Plan Mode first, Explore subagent for search, /clear between tasks, cache-friendly ordering, Haiku for mechanical work, background agents, fewer permission prompts. Each missing habit is one click to bake into the plan.
• Usage ledger — every claude call Adeptly makes (recipe, crew, feature-refresh) records its real token/cost receipt to .adeptly/usage.jsonl. A local Usage panel shows spend, cache-hit %, and cost by source and model. No telemetry — the ledger never leaves your machine.
• Cost estimates — the recipe's expected turns + cost show up front; the crew shows estimate vs. actual after a live run.
• Refresh features from your CLI — the built-in catalogue is a snapshot that goes stale. Hit Refresh and Adeptly asks your own (self-updating) claude CLI what's new, validates it, and lets you accept additions. No backend, no doc-scraping — your CLI is the one always-current source.

All local-first, all keyed off your existing claude CLI — same trust surface as before.

🚀 New in v0.5 — Crew: run the plan, don't just write it

Adeptly used to stop at the recipe (the plan's list of which Claude features to use). Now it closes the loop: the Crew executes that recipe, so the subagents, skills, and hooks Adeptly taught you about actually run — as a pipeline of roles, each a headless claude turn in your own repo:

Architect → Approval Gate → Builder → Medic → Reviewer → Security → Pilot (PR)

• Architect maps the code and confirms the approach (read-only).
• Approval Gate blocks anything from running until the plan is approved.
• Builder branches and implements the plan with the smallest sensible diff.
• Medic runs your build/tests and self-heals once if they fail.
• Reviewer + Security review the diff for regressions and security issues.
• Pilot commits, pushes, and opens the PR.

Safety first:

• Dry-run by default. Simulates the whole pipeline — no git, no claude, no PR. Run it anytime to preview the crew.
• Live runs are double-gated: the plan must be approved and you must start Adeptly with ADEPTLY_LIVE=1. Without both, live is refused.
• Still 100% local. The crew drives your claude CLI in your repo. Nothing new leaves your machine.

# enable real git + PR actions (off by default)
ADEPTLY_LIVE=1 npx adeptly

Every run is written to docs/plans/runs/<slug>/ as JSON + an append-only audit.jsonl — a full, reviewable trail of what the crew did.

Install

Requirements: Node 18.17+ and a working Claude Code CLI on your PATH.

# install claude code if you don't have it
npm install -g @anthropic-ai/claude-code

# try once without installing
npx adeptly

# or install globally
npm install -g adeptly
adeptly

Run it from inside any project folder. Adeptly scans docs/plans/ and creates it if missing. If Claude Code isn't installed it'll show a banner with the exact install command and link to the docs.

CLI flags

adeptly [options]

  --host <ip>          bind address (default 127.0.0.1)
                       use 0.0.0.0 to expose on your LAN
  --port <n>           preferred starting port (default 3000)
  --no-open-browser    skip the auto-open (useful over SSH / inside Docker)
  -h, --help           show usage

Env vars: PORT (= --port), ADEPTLY_NO_OPEN=1 (= --no-open-browser).

The product loop

1. Open chat. No plan selected? Describe what you want to build:

   "I want to refactor auth in our Next.js app to support passkeys alongside passwords."

2. Claude drafts the plan. Full markdown with # Problem, ## Approach, ## Files to change, a Mermaid flow diagram, ## Risks, and ## Approval — and with specific Claude Code features named in the right sections ("Use Plan Mode before writing code", "Run /security-review before merging the session middleware").

3. Read it. Feature names are underlined inline with hover tooltips. The bottom strip shows numbered suggestions ("line 19: skill-security-review matched on 'password'"). The right panel catalogues all 30+ Claude Code features.

4. Refine via chat. Ask Claude "What about token cost?" — and below the reply you get an Add to plan card with content + a section target. One click, the recommendation lands in ## Risks or wherever it belongs.

5. Voice-driven or hands-free. Click the 🎙️ mic to dictate in the chat (push-to-talk, browser Web Speech API). Or paste a screenshot with Ctrl+V and ask Claude to read it.

6. Generate a recipe. The ✨ Claude recipe tab calls your local claude --print and returns a structured workflow: subagent allocation by purpose, skills with when-to-invoke, hooks worth setting up, expected turns, step-by-step execution order.

7. Approve. Status flips draft → in-review → approved. When all reviewers sign off, the editor pulses mint-green for 1.5s.

8. Copy plan + recipe as a Claude Code prompt and paste into a fresh Claude Code session. Or just hand off the markdown file to your teammate.

9. Or run the crew. Open the Crew tab and hit Run — Adeptly executes the whole plan (branch → build → test → review → PR) through the role pipeline. Start in Dry-run to preview; switch to Live once the plan's approved.

Multi-developer workflow

Plans are markdown files in git. That's the entire sync model.

• Awareness: the plans list shows git author + dirty-state markers, so you see who last touched what at a glance.
• Review: approvals live in docs/plans/approvals/<slug>.json alongside the plan. PR reviewers can read the plan markdown directly in GitHub's UI without installing Adeptly.
• No conflicts: each plan is its own file. Three devs on three plans never collide. Two devs editing the same plan resolve through normal git merge.
• No backend: Adeptly is local-first. No accounts, no central server, no real-time sync layer to fail.

Folder structure

your-project/
  docs/
    plans/
      <slug>.md                 # the plan (markdown + Mermaid)
      approvals/
        <slug>.json             # reviewer state
      recipes/                  # gitignored — generated recipes
        <slug>.json
  .adeptly/                     # gitignored — chat uploads & runtime data
    uploads/

.adeptly/ and docs/plans/recipes/ are local-only; add to your .gitignore if Adeptly hasn't already.

Keyboard shortcuts

FAQ

Q: Do I need a paid Claude account?
Yes — you need Claude Code installed and signed in. Adeptly shells out to claude --print; it never holds an API key of its own. The whole point is "use what you're already paying for, better."

Q: Does my code get sent to Anthropic?
Only when you invoke chat or recipe generation. At that moment Adeptly sends the current plan + your message + the Claude Code feature catalogue to your local claude CLI, which sends that to Anthropic — exactly as if you'd typed it into a claude terminal yourself. Adeptly itself never opens an outbound connection to anything other than claude.

Q: Why a web UI instead of a TUI?
Mermaid diagrams. Inline keyword underlining. Markdown rendering with images and tables. Multi-pane drag-to-resize. A terminal can't carry the planning experience we wanted.

Q: Does it work offline?
The UI does. Chat doesn't — it needs claude --print, which needs the internet to reach Anthropic.

Q: Cursor / Continue / Aider — why this and not those?
Those tools generate code. Adeptly starts one step upstream: it generates and refines the plan that becomes a Claude Code prompt. With the Crew it can also drive the implementation end-to-end (branch → build → test → PR) by orchestrating your own claude CLI — but the plan, and your approval, always come first.

Q: Can my team use it together?
Yes. Everyone installs adeptly and points it at the same repo. Plans are in git; approvals are in git; conflicts resolve like any other markdown file. No central server, no accounts.

Q: Can I run it on a remote server / through a tunnel?
Not officially yet. Roadmap includes --host and Cloudflare Tunnel support. For now it's localhost-only.

Q: Where can I report bugs / request features?
GitHub issues. Or DM in r/ClaudeAI / r/programming when this lands.

Contributing

Adeptly is open source (MIT) and contributions are welcome — the codebase is a single Next.js app with a small local Node server, no backend, no accounts.

git clone https://github.com/ShopDevX/adeptlydev.git
cd adeptlydev
npm install
npm run dev        # http://localhost:3000

See CONTRIBUTING.md for the dev workflow, how the plan/recipe/crew pieces fit together, and the PR checklist. Good first issues are labelled good first issue. By participating you agree to the Code of Conduct.

Roadmap

• Plan creation from chat, inline feature highlighting, recipe generation, approval workflow
• Crew runner — execute a plan as a role pipeline (dry-run + live)
• Stack auto-detection — reads your manifests (package.json, go.mod, Cargo.toml, …) so the plan + recipe tailor to your actual stack
• Feature Coverage + Token Hygiene — score how much of Claude Code a plan uses and how lean it is on tokens
• Usage ledger — meter Adeptly's own claude spend locally (cost, tokens, cache-hit)
• Refresh catalogue from your CLI — keep the feature list current without a backend
• Session handoff — leave a resume note the next Claude session picks up
• Whole-account usage — parse ~/.claude transcripts for machine-wide spend
• Per-run history browser + re-run from a previous run
• Remote/tunnel support (--host, --tunnel via Cloudflare)
• Parallel crew stages — Reviewer + Security run concurrently
• Crew theming (swap role names/colors — "movie crew" packs)
• Auth for exposed/tunnel mode (token gate)

Status

v0.8.x — beta on npm. Feature set: plan creation from chat, inline feature highlighting, multi-dev git awareness, recipe generation, crew runner (dry-run + live, parallel Reviewer+Security), crew run history + re-run, session handoff, stack auto-detection, feature coverage + token-hygiene scoring, usage ledger + whole-account usage (~/.claude), cost estimates, refresh feature catalogue from your CLI, remote/tunnel (--host, --tunnel), approval workflow, command palette, focus mode, drag-resize splitters, voice input (push-to-talk), file + image upload, dark + light themes.

• npm: https://www.npmjs.com/package/adeptly
• repo: https://github.com/ShopDevX/adeptlydev

License

MIT.

Built by

ShopDevX.