Masterwork

A local workbench for the skills and subagents your AI coding agent uses — browse them, edit them, refine them with AI, and prove they work with scored simulation runs.

Writing a skill is easy. Knowing whether it actually fires at the right moment, does the right thing, and doesn't quietly overfit to the one example you wrote it against — that's the hard part. Masterwork is built for that second half.

Runs entirely on your machine. Your skills never leave it.

What it does

• Browse & edit every skill and subagent installed on your machine, with search, diffs, and git-backed snapshots of every change.
• Simulate — run a skill against a scenario, score the result against a checklist, and see exactly which criteria it missed. Re-run after edits to confirm the fix.
• Generality audit — catch skills that were tuned to one example and won't survive contact with a different repo.
• Chat to refine — describe the change you want; the assistant proposes a concrete diff you accept or reject. It never writes files on its own.
• Projects — group assets around a goal, with generated summaries and Mermaid diagrams of how they fit together.
• Sessions — record the runs your coding agent actually does: which skills and subagents each one used, where the time went, what it cost. One click to switch on.
• Global instructions — edit your agent's root instructions file in the same place as everything else.

Requirements

• macOS or Linux
• Python 3.13+ and uv
• Node 20+
• The Claude Code CLI, signed in

No database server needed — it uses SQLite at ~/.masterwork/masterwork.db and stores only chat sessions and simulation history. Your skills stay on disk. Postgres is supported too: set DATABASE_URL and the same migrations apply.

The built-in assistant shells out to your local claude binary, so it runs on your existing subscription. No API key, no inference bill.

Quick start

npx masterwork

That's it — nothing to clone. It installs what it needs, migrates the database, starts both servers and opens the browser. Ctrl-C stops everything.

From a clone, if you want to hack on it

git clone https://github.com/flieks/masterwork.git
cd masterwork
npm start          # same launcher

Or run the two servers yourself:

cd backend
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --port 8008

# in a second terminal
cd frontend
npm install
npm run dev        # http://localhost:5192

Session recording

The Sessions screen is empty until your coding agent tells masterwork that a run happened. Open it and click Connect — that is the whole setup. It:

• copies a small forwarder script to ~/.masterwork/hooks/,
• adds seven hooks to ~/.claude/settings.json that run it (backing the file up to settings.json.masterwork.bak first),
• leaves every other hook in that file exactly as it was.

From then on each session posts its start, prompts, tool calls, subagent spawns and exit to http://localhost:8008/api/v1/hooks/events. Disconnect in the same place removes those seven entries and nothing else; the runs already recorded are kept.

Nothing is installed without that click, and nothing is sent anywhere but your own machine. Prefer the terminal?

cd backend && uv run python -m app.observability.cli connect

Claude Code is the only agent wired up today. SKILL.md is an open standard and so is this: an agent that can run a command on session events is an Integration implementation in backend/app/observability/ and a line in its registry — the API, the screen and the button already handle the rest.

How it works

frontend/   React + Vite + TS · Jotai + jotai-tanstack-query · react-router-dom · shadcn/ui
            API client generated (typescript-axios) from the backend's /openapi.json
backend/    FastAPI · Pydantic v2 · SQLAlchemy 2.0 async · Alembic · uv
            - assets:        scans provider roots (~/.claude/skills, ~/.claude/agents)
            - instructions:  the global CLAUDE.md
            - chat:          claude -p subprocess runner, proposals, apply-changes
            - simulations:   scored dry-runs with checklist grading and run memory
            - sessions:      hook ingest, plus the per-agent wiring that installs it
docs/       SPEC.md (product spec) · API_CONTRACT.md (the v1 API contract)

The files on disk are the source of truth. The database holds chat sessions and simulation history — nothing that can't be rebuilt.

Safety model

This tool edits files in your home directory, so the boundaries are explicit:

• The assistant is given read-only tools. It cannot write anything.
• The only file outside masterwork's own home it ever writes is your agent's hook config, only when you click Connect, and only after backing it up.
• Every change arrives as a proposal you review and accept.
• Applies are performed by the backend, against a validated path allowlist.
• Each accepted change is committed as a git snapshot, so you can always go back.
• Secrets found in the files being read are redacted before they reach the model.

No auth, no multi-user: this is a single-user tool bound to localhost.

Roadmap

• More agents. SKILL.md is an open standard — Codex, Cursor, Gemini CLI and others read the same files. The backend already routes through a provider abstraction for assets and an integration abstraction for session recording; adding an agent to either is the natural first contribution.
• A faster first run. npx masterwork currently runs the frontend through Vite's dev server, so the very first launch waits on a full install. Shipping a pre-built frontend would cut that to seconds.
• A hub. Publish and pull skills, subagents and projects — with simulation scores attached, so you can see what a skill actually does before installing it.

Issues and PRs welcome, especially for the first item.

Development

Backend tests (integration tests use a throwaway masterwork_test database):

cd backend && uv run pytest

Frontend tests (Playwright component + E2E):

cd frontend && npm run test:ct && npm run test:e2e

Local dev-server setup, including the optional launchd services used on macOS, is documented in docs/DEV_SETUP.md.

Credits

The factory/ pipeline — staged agent runs with typed envelopes, per-stage write boundaries and deterministic gates — takes its shape from disler/super-simple-software-factory by IndyDevDan. SSSF in a couple of code comments refers to that repo. The code here is ours; the idea to structure it this way is not.

License

Elastic License 2.0: free to use, self-host, and modify. You may not offer Masterwork (or a substantial part of it) to third parties as a hosted or managed service.