devkit is how Firefly Software developers work with Claude Code and Codex. Every repository is in a predictable place. Every project has a living handoff note and a task board that a team, its Macs, and its agents share safely. Every agent session starts from the current state, keeps you informed while it works, and ends by recording what changed. The workspace never fills up with stray worktrees, sibling copies, or gigabytes of forgotten build output. One install sets up the toolchain, git, Claude Code (CLI and Desktop), Codex (CLI and the ChatGPT app), skills, plugins, Docker and the background automation, and keeps them that way.
Why · Install · A quick tour · From plan to operate · Features · For your agents · When devkit fails · How it fits together · What's inside · Docs · Credits
| Without devkit | With devkit |
|---|---|
| Each session rediscovers the project | The session starts with the project's handoff note, tasks, locks, git state, commands, and the last status |
| Two people (or two agents) pick up the same task | dev task start locks it on every machine at once; every change records who, when, and why |
| "How is it going?" | Agents report progress with an ETA computed from their real pace, and you get a notification when they finish or get stuck |
| A crew question or a CI result waits until you type something | One wait, dev watch --wait, wakes an idle session for each crew question, decision, ready step, and CI result; a turn that would leave nothing to wake it is sent back |
Worktrees and repo-pr12 copies pile up; disks fill |
One managed worktree location, dev wt new to put each worktree there, and safe automatic cleanup once work is merged |
| Push → CI → fix → push → CI … | dev ci --run runs what CI runs, here; dev push pushes once, only with that evidence; dev ci status follows the one CI run with an ETA on GitHub, GitLab, Bitbucket, or Azure |
| PRs with empty descriptions, merges past red checks | dev pr create fills the PR template and refuses an empty "What and why"; dev pr merge waits for green checks and reviews; dev release tags and publishes by the policy |
| Every project releases its own way, or not at all | dev delivery detects and records a delivery policy (versioning, test gate, changelog, release flow); dev release refuses tags that break it |
An agent's rm -rf or cp destroys work |
dev rm, dev mv, and dev cp use the Trash, refuse open or unsaved files, and dev rm --undo restores them |
claude/vigilant-jang-ec71c0 branches and AI attribution |
Trunk-based naming (feat/PROJ-142-invoice-export) and no attribution, checked by dev branch new, dev commit, and dev push for both agents |
| Claude and Codex behave differently, and settings drift | One set of rules, skills, and hooks for both; drift is repaired; dev config diff previews everything |
| Agents skip the skill that fits the job | Required skills follow the files, commands, and kind of work, in any language: added to subagent briefs, and checked before a turn ends |
| Nobody knows what is in flight | A shared handoff repository with initiatives, projects, task boards, a team view, status reports, and a dashboard, synced within seconds of every commit, push, and PR |
| The same mistake, made again next month | Blameless lessons, recalled before the work they apply to; devkit records exposure and observed repeats, and a lesson that keeps repeating becomes a test or a lesson rule |
| Every agent rediscovers the same devkit bug | A public bug registry: a detour found once reaches every agent, and votes rank what the next hotfix fixes |
| "What did the agent do last night?" | Scheduled jobs you can see and change, and an audit trail of every change and job run, for the whole team |
| "Did the agent even read the rules?" | Every reply starts with the [Firefly> DevKit] status block; devkit checks it, scores it, records it, and reports deviations |
devkit is for Macs with Apple silicon: it installs its tools with Homebrew, and Homebrew no longer installs on Intel Macs. An Intel Mac that already has Homebrew can still run it. In Terminal, run:
curl -fsSL https://raw.githubusercontent.com/fireflysoftwaresolutions/devkit/main/install.sh | bash
exec zsh && dev doctor # every check passesThe installer makes sure Homebrew, git, Python, and the GitHub CLI are present, downloads the newest devkit release to
~/Development/fireflysoftwaresolutions/devkit, signs you in to GitHub, and starts the setup wizard. The wizard asks
for your workspace, your handoff repository (yours, or one your team shares), which agents to configure, your stacks
and the Docker VM, shows the plan, and applies it: the toolchain for your stacks, git signed in with your GitHub
identity, Claude Code and Codex, the devkit plugin and the curated skills in both, and the scheduled jobs. The hooks
then run a read-only, checksummed copy of that release, so no edit can switch them off by accident. It is
safe to run again, and dev update later moves devkit to the newest release and pins it.
New to the terminal? Your first install, step by step explains every screen, and the tutorials walk through a first task in Claude Code, Claude Desktop's Code tab, Codex CLI, or Codex in the ChatGPT app.
To read the script before you run it:
curl -fsSL https://raw.githubusercontent.com/fireflysoftwaresolutions/devkit/main/install.sh -o install.sh
less install.sh
bash install.shPass options after bash -s --, for example curl -fsSL … | bash -s -- --yes:
| Option or variable | Effect |
|---|---|
--yes |
Accept every default in the setup wizard |
--skip-packages |
Skip toolchain packages for this run; bootstrap prerequisites and selected-agent installers still apply |
--no-setup |
Get devkit and its prerequisites, but do not sign in or run the wizard |
DEVKIT_HOME |
Where devkit goes (default ~/Development/fireflysoftwaresolutions/devkit) |
DEVKIT_REPO |
The repository to clone, for example your fork |
DEVKIT_REF |
A tag or branch to check out instead of the newest release |
Set a variable for bash, not for curl: curl -fsSL … | DEVKIT_REF=v26.11.3 bash. Everything the installer and the
wizard change on your Mac, and how to undo each change, is listed in
Getting started › What devkit touches.
dev your workspace at a glance
dev dashboard the live command center; it opens on Now: does anything need you?
dev overview every initiative and project: status, progress, Now tasks, latest status
dcd billing jump into a project dwt feat/invoice-export …or into a new worktree
dev task the project's board dev task add "Export invoices as CSV" --type feature --now
dev task start <id> claim it (locked on every machine) dev task done <id> dev task release <id>
dev task delegate <id> --to jordan --why "Jordan owns the event bus" hand it over, with the message to send
dev plan new "Refund events" --kind spec a versioned spec; dev plan revise <file> --why "…"
dev initiative show payments one initiative across its projects dev task -i payments
dev team who is working on what, on every machine
dev progress live runs with ETA dev time where the time goes
dev crew graph the run, its crew lanes, decisions, and messages dev crew next who to launch next
dev watch --wait wake on the next crew question, decision, or CI result dev watches every wait
dev report --days 7 a status report for the team, in Markdown
dev claude api -w feat/x Claude Code in a managed worktree dev codex api Codex in the project
dev branch new feat/invoice-export a branch from an up-to-date main
dev commit -m "feat(invoice): add CSV export" a Conventional Commit, never on main
dev ci --run run what CI runs, here, and record it dev push one push, with that evidence
dev pr create the PR, from the template dev pr checks --watch wait for CI
dev pr merge when checks and reviews allow it dev release tag and publish by the policy
dev ci status --watch the branch's pipelines: jobs, current step, ETA (GitHub, GitLab, Bitbucket, Azure)
dev ci watch --wait --pr 12 wake when that PR's CI ends dev backup this branch, when no CI starts
dev lesson add "…" --happened "…" --cause "…" --prevent "…" --file … a lesson, recalled before that work
dev bug devkit's own known bugs and their detours dev bug top what the next hotfix fixes
dev jobs the scheduled jobs and their last runs dev audit --team what devkit did, everywhere
dev delivery the project's release policy and gaps dev delivery apply --why "…" record it
dev files · find · grep · diff token-light views of the tree, names, contents and changes
dev rm build/out.log to the Trash, refuses unsaved work dev rm --undo put it back
dev sec scan secrets, dependencies, code, IaC and workflows
dev gc what can be reclaimed safely (dry run)
dev doctor verify the whole setup dev agents test a live check of both agents
dev ext ls pinned plugins, skills, and MCP servers dev ext outdated what upstream has now
dev update --check is a newer devkit out? (read-only) dev update move to it, in your terminal
All commands are in docs/commands.md.
Every stage of the lifecycle has a devkit command and a skill, so nothing falls between them. The table with each stage's guide is in Concepts › From plan to operate.
| Area | What you get | Guide |
|---|---|---|
| Workspace | One canonical path per repository on any git host, managed worktrees, safe cleanup | Concepts and Disk and cleanup |
| Handoff | A private (or team) handoff repository with notes, the projects map, task boards, and activity, kept current by a sync after each session and every hour | Concepts |
| Teams and machines | Versioned work items with locks that every machine sees and that run out when nobody works on the item's branch, items that close when their branch merges, reasons for every change of scope, versioned plans, append-only session logs, presence, dev team |
Teams and machines |
| Work states | What devkit shows stays true: work items, runs, crew lanes, decisions, waits and CI watches, the install, and branches each end when their work ends, and dev doctor and the dashboard report what drifted, with the command that fixes it |
Work states |
| Initiatives | Cross-project goals with workstreams, cross-project tasks, honest progress, and adoption of older handoff repositories | Initiatives |
| Progress and communication | dev progress with active time, per-step estimates and dependencies, a critical-path ETA range, a plan that changes only with evidence, reminders, notifications, one wait that wakes an idle agent for every devkit event (dev watch --wait), a short welcome when a session starts, dev time, message templates, dev report |
Progress and communication |
| The crew | 25 specialist agents, named by role, and the tech lead (Morpheus), the main session that leads them, for Claude Code and Codex from one roster: slots that follow your usage, lanes with their own time, file scopes with advice when a member writes outside its own, messages, routing and delegation, guided or automatic decisions, and a status block every member must end with | The crew |
| Status block | Every reply starts with a [Firefly> DevKit] block (done, check, progress, next) that devkit checks, scores, and shows everywhere; while a run is active it always says which step of how many is running |
Concepts |
| Dashboard | A live, local, read-only command center that opens on Now (does anything need you, and when does the running work land?), then tasks, background work, team and crew, projects, initiatives, activity, explorer, and health | Dashboard |
| Claude Desktop and ChatGPT | The same setup in Claude Desktop's Code tab and the ChatGPT app's Codex; a devkit extension with 21 tools for Desktop chat and Cowork | Agents |
| Delivery | dev ci, local integration, one push and one CI run, CalVer, and no blind re-runs |
Delivery |
| Git and GitHub | dev branch, commit, rebase, push, pr, run, release, and issue: local CI evidence before every push, the PR template filled and checked, gated merges, releases by the policy, WIP commits instead of a shared stash |
Git and GitHub |
| Delivery policy | dev delivery detects how a project versions, tests, and releases, recommends a policy, and records it; sessions see it and dev release enforces its tags |
Delivery › The delivery policy |
| CI/CD status | dev ci status [--watch] for GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure Pipelines: jobs, current step, elapsed time, and an ETA |
Commands › dev ci status |
| CI/CD pipelines | dev ci audit finds what makes a pipeline slow, unreliable, or unsafe on all four hosts, and --fix applies the safe GitHub fixes; dev ci init writes a pinned pipeline with security scans and signed releases; dev ci watch follows every run after a push, reports each result once, and hands a failure, diagnosed, to the Release engineer (Link); dev ci watch --wait wakes an agent that waits on one run, and the session's one dev watch --wait covers every run devkit follows |
CI/CD pipelines |
| Testing | dev test runs the last failures first, then only what your changes can break; dev test audit finds tests that cannot fail, and dev test prove checks that new tests fail without the change; dev ci --run --resume repeats only what a fix affects |
Testing |
| Unfinished work | dev stubs finds TODOs, placeholders, and stubs without a task; the end of a turn sends them back, and a commit that would take them gets a warning |
Commands › Quality |
| Files | dev files, find, grep, and diff with compact, capped output; dev rm, mv, and cp with the Trash, undo, and refusals instead of lost work |
Commands › Files |
| Lessons | Blameless lessons from mistakes, recalled before the work they apply to, measured by exposure and observed repeats, screened before any agent sees them, turned into tests and lesson rules when they repeat, and consolidated every night by dev sleep without losing any that still matter |
Lessons |
| Bug registry | When devkit itself fails, agents get the known detour from a public registry in GitHub Issues, share the ones they find under trust rules, and report what nobody solved, with devkit facts only; votes rank the bugs for hotfixes | The bug registry |
| Scheduled jobs and audit | Sync, sleep, cleanup, repair, audit, update check, health, and lesson review as launchd jobs you can see and reschedule; an audit trail of everything devkit changed or decided, with secrets redacted | Scheduled jobs and the audit trail |
| Git hosts and clouds | Installs and checks the hosts and clouds you select, including GitLab, Bitbucket, Azure DevOps, AWS, Azure, Google Cloud, DigitalOcean, Kubernetes with Helm, and OpenTofu. GitHub is part of the base setup | Getting started |
| Languages and frameworks | Choose runtimes separately from Angular, React, Next.js, NestJS, Spring Boot, Laravel, and Symfony. Setup, updates, extensions, skills, and checks share the selection; existing installations retain legacy defaults until customized | Configuration |
| Security | dev sec scan (gitleaks, osv-scanner, Semgrep, Trivy, zizmor), a secret check before every commit, devkit run isolated from Python's environment, and the DevSecOps skills and plugins |
Skills and plugins, Security policy |
| Permissions | Agents run with the permissions you give them, at your risk: devkit records each call and adds advice, and never refuses one or asks you for a grant. Its own commands still check their work (dev commit refuses staged secrets, dev push needs local CI evidence, dev release follows the delivery policy). devkit is not a security boundary: agents work with your own gh account and keys, and your review remains the boundary |
Concepts › Agents act with your permissions, Security policy |
| Backups and continuity | dev backup copies branches that exist only on this Mac to the remote when that starts no CI run, with a policy per project and embargoes; a session keeps its run, crew, and your requests through compaction |
Delivery, Continuity |
| Skills | A curated, pinned catalog for both agents, optional groups, and required skills enforced per kind of work; the impeccable design engine for frontend work, run through dev impeccable with its digest checked |
Skills and plugins |
| Extensions | dev ext lists every third-party plugin, skill, and MCP server with its pin, shows what upstream has now, reports drift, and lets you add your own or turn one off |
Skills and plugins › Who changes extensions |
| Shell | Tab completion for zsh and bash, generated from dev itself; dcd and dwt; fzf pickers for work items, projects, and branches when you turn them on (dev setup shell) |
Getting started › Tab completion |
| Updates | dev update moves devkit to the newest release and pins it, and names the running sessions to restart; a session still on the older release never undoes it; dev update --check says, read-only, whether one is out and what changes, and a daily job asks for you |
Getting started › Updating |
| Models and tokens | Your model stays yours; the Lookup scout (Sparks), read-only; Codex profiles, a cap on parallel threads, and routing rules | Models and tokens |
| Templates | Plans, specs, spikes, bug fixes, ADRs, typed tasks, and a pull request description | Templates |
| Docs and diagrams | dev docs check, plus validated, branded SVG diagrams in a dark and a light version |
Diagrams |
| Docker | Colima with Compose, Buildx, and Testcontainers | Docker |
devkit is also a plugin for Claude Code and Codex, installed automatically:
- Context in, record out. Each session receives the project's handoff note, tasks, locks, initiatives, branch, PRs, commands, the last status, and the known pitfalls; its commits, status, and session line are recorded and the handoff repository is pushed within seconds.
- A welcome. Each session opens with
dev statusin at most five lines: whether anything needs you, what is running, what is next, and where you are. It shows in Claude Code and Codex, in the terminal and in the desktop apps. - Kept informed. Agents post a plan with an estimate, progress updates with an ETA, and a final report; the hooks answer "how is it going?" from real records and remind a quiet agent to update you.
- Nothing waits unseen. An idle session's
dev watch --waitwakes it for each crew question, answer, decision, ready step, and CI result, and a crew member waits for its own answer withdev watch --wait --for me. - A crew. 25 specialist agents (the Senior engineer, the Frontend and Backend engineers, the Software architect, the Code reviewer, the Release engineer, and the rest) that the main session leads as the tech lead (Morpheus): each kind of work goes to the member the RACI makes Responsible, in a lane with its own files and time, and the run ends when each approver has reviewed the work they own.
- Slash commands:
/devkit:status·/devkit:overview·/devkit:task·/devkit:handoff·/devkit:standup·/devkit:progress·/devkit:crew-status·/devkit:test·/devkit:stubs·/devkit:ship·/devkit:ci·/devkit:dashboard·/devkit:doctor·/devkit:reconcile(skills of the same name in Codex). - Skills:
using-devkit,handoff,communicating,working-efficiently,crew,wait-and-wake,work-state,workspace,delivery,release-policy,testing,cicd,learning-loop,root-cause,research,functional-analysis,backend,devsecops,docs, anddiagrams, plus a curated, pinned set for architecture, Angular, React, Spring, testing, security, and observability. Required skills are enforced for each kind of work. - Rules: one set of global instructions for both agents: the status block on every turn, method, replies in your language with code and records in American English, progress and time, learning from mistakes, token use, files and disk, worktrees, branches, commits, delivery, backend practice, required skills, the team protocol, and handoff.
- Pre-tool hook: records each tool call, routes a crew member's devkit calls to its lane, and adds advice to the call (a write outside a member's scope, a lesson anchored on the command). It never refuses a call: agents act with your permissions, so keep reviewing what they do.
- Continuity: after a compaction, a resume, or
/clear, the session gets devkit's record of its run, the crew working now, the decisions waiting, and your latest requests, which wins over the summary.
When a dev command crashes or a hook fails, devkit says the bug is its
own, not your project's, and looks it up in a public bug registry kept in this repository's GitHub Issues. If someone
already found a workaround, your agent gets it and carries on. If not, the agent looks for one and shares what works,
or stops the blocked work and continues independent tasks. Safe reports are captured automatically and queued for
retry under your configured GitHub account. No manual submission or consent prompt is required. They contain validated
devkit facts, never project paths, names, code, or output. Security-sensitive and legacy free-text payloads remain
held for private handling; uncertainty never falls back to public posting. Votes rank the bugs, so each hotfix fixes what hurts most. See
The bug registry.
Concepts › How devkit fits together explains each part, what happens in a turn, and which check enforces which rule; A request from start to release follows one change through them.
| Path | What |
|---|---|
bin/dev, lib/devkit/ |
The dev CLI (Python 3.9+, standard library only) |
plugin/ |
The devkit plugin for Claude Code and Codex: skills, slash commands, the crew's agents (generated from config/crew.json), identity |
agents/AGENTS.md |
The global instructions generated into ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md |
config/ |
What devkit manages, such as Claude and Codex settings, hooks, plugins, MCP servers, profiles, pinned skills, skill rules, git, and docs defaults |
templates/ |
Plan, spec, spike, bug-fix, and ADR templates; task templates; the pull request template; the handoff repository README; the pinned CI/CD pipelines of dev ci init (templates/ci/) |
install.sh, Brewfile |
Bootstrap and toolchain |
shell/ |
zsh integration (dcd, dwt, the opt-in pickers, Docker environment) and the Tab completion for zsh and bash, generated from the parser (shell/completions/) |
tools/brand/ |
Renders devkit's icon and banners from the Firefly brand elements |
tools/dashboard_shots.py |
Screenshots of the dashboard from neutral fixture data, at a true viewport, for reviews and the docs (--help has the guide) |
docs/ |
The guides, diagram specs, and images |
tests/ |
Unit tests (python3 -m unittest discover -s tests -t .) |
| Guide | For |
|---|---|
| Getting started | Your first install step by step, the setup wizard, the pinned copy, Tab completion and the zsh helpers, onboard a developer, update, uninstall |
| Where to use devkit | The surfaces compared: what devkit does in Claude Code, Claude Desktop, Codex CLI, and the ChatGPT app |
| Tutorials | A first task with the crew in Claude Code, Claude Desktop's Code tab, Codex CLI, and Codex in the ChatGPT app; Claude Desktop chat and Cowork for status and plans |
| Concepts | Layout, how work is organized, the handoff repository, worktrees, agents' permissions and the pre-tool hook, the status block, the session-start welcome, and the background sync |
| Teams and machines | Work items and locks, shipped and stale items, reasons, and history, versioned plans, session logs, presence, merge rules |
| Work states | The states of work items, runs, crew lanes, decisions, waits and CI watches, the install, and branches: what moves each, and how to repair drift |
| Initiatives | Cross-project initiatives, progress, adopting an older handoff repository |
| The crew | The 25 specialist agents and the tech lead (Morpheus): who does what, slots, lanes, scopes, messages, delegation, guided or automatic decisions, moot and withdrawn decisions, how your answers count, and rooms (planned) |
| Continuity | What a session keeps through compaction, resume, and /clear, and dev session |
| Progress and communication | dev progress, the time model and ETA, notifications, waiting and waking, dev time, message templates, status reports |
| Commands | Every dev command and option, including git and GitHub, dev progress, dev crew, dev test, dev stubs, lessons, jobs, the file commands, and dev ci |
| Dashboard | The live command center: the server, Now, the views, Background work, the crew, drawers, shortcuts, routes |
| Configuration | Every key of ~/.config/devkit/config.json, personal rules, environment variables |
| Agents | What is configured in Claude Code and Codex, hooks, devkit always on |
| Skills and plugins | The devkit plugin, required skills, the curated catalog, dev impeccable, dev ext and drift, what was left out |
| Models and tokens | Models, effort, subagents, the Lookup scout (Sparks), Codex profiles |
| Templates | Plans and specs, tasks, the pull request template |
| Git and GitHub | Branches, commits, local CI evidence, pushes, pull requests, CI runs, releases, and issues through dev |
| Testing | dev test: failures first, then the blast radius; tests that can fail; TDD with devkit |
| CI/CD pipelines | dev ci audit, --fix, dev ci init, dev ci watch, and the agent's wait, dev ci watch --wait, on GitHub, GitLab, Bitbucket, and Azure |
| Delivery | Local-first GitOps: the delivery policy, one integration, one push, one CI run, following CI, releases |
| Lessons | Learning from mistakes: lessons, recall before the work, observed outcomes, held lessons, lesson rules, dev sleep |
| The bug registry | When devkit itself fails: known detours, what is sent and never sent, trust, automatic safe reporting, dev bug, hotfix rankings |
| Scheduled jobs and the audit trail | The background jobs and their schedules, logs, and journal; the audit trail |
| The audit trail | What each record holds, the hash chain and dev audit verify, exports, retention, and the GDPR rights of the people recorded |
| Diagrams | dev diagram and the diagram design rules |
| Disk use | dev du, what is safe to delete, Colima's disk, dev free |
| Disk and cleanup | dev gc safety rules and automatic cleanup |
| Docker | Colima, Compose, Buildx, Testcontainers |
| Troubleshooting | Logs, common problems, pin refusals and rollback, resetting |
| Developing devkit | Code layout, tests, brand assets, release process |
devkit is designed and maintained by Andrés Contreras Guillén for Firefly Software Solutions Inc.
Copyright © 2026 Firefly Software Solutions Inc. Licensed under the Apache License 2.0; see LICENSE. Third-party skills and tools installed by devkit keep their own licenses; see NOTICE.
Contributions are welcome: the contributing guide explains how to propose a change and the checks a pull request must pass. Report a vulnerability privately, as the security policy describes, never in a public issue.