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 · 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 |
Worktrees and repo-pr12 copies pile up; disks fill |
One managed worktree location, a guard that blocks stray ones, 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); the guard 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; the guard steers raw deletes to them |
claude/vigilant-jang-ec71c0 branches and AI attribution |
Trunk-based naming (feat/PROJ-142-invoice-export) and no attribution, enforced for both agents |
| Claude and Codex behave differently, and settings drift | One set of rules, skills, and hooks for both; drift is blocked and 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 at the start of every session; a repeat is counted, and a recurring lesson becomes a test or a guard rule |
| "What did the agent do last night?" | Scheduled jobs you can see and change, and an audit trail of every change, guard decision, 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 macOS only (Apple Silicon and Intel). 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
and the guard 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 |
Configure only; do not install the toolchain packages for your stacks |
--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: tasks, background work, team and crew, projects, initiatives
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 2 claim it (locked on every machine) dev task done 2 dev task release 2
dev task delegate 3 --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 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 lesson add "…" --cause "…" --prevent "…" a lesson every later session recalls
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
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, reasons for every change of scope, versioned plans, append-only session logs, presence, dev team |
Teams and machines |
| 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, 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 the guard enforces, 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 |
Concepts |
| Dashboard | A self-contained HTML command center: home, initiatives, projects, team, tasks, activity, explorer, 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 20 tools for Desktop chat and Cowork | Agents |
| Delivery | dev ci, local integration, one push and one CI run, CalVer, a push budget, 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 the guard 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 and hands a failure, diagnosed, to the Release engineer (Link) |
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 and every commit refuse them |
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 as known pitfalls in every session, counted when they repeat, turned into automation, and consolidated every night by dev sleep |
Lessons |
| Scheduled jobs and audit | Sync, sleep, cleanup, repair, audit, 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 | The CLIs for GitLab, Bitbucket, Azure DevOps, AWS, Azure, Google Cloud, DigitalOcean, Kubernetes, and OpenTofu, installed and checked for sign-in | Getting started |
| 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, Guard rules |
| Guard | A pre-tool hook that blocks what wastes time or disk or breaks shared records, holds irreversible actions for your grant, and explains the right way. It is a seatbelt, not a sandbox: it catches an agent's mistakes and common prompt injection, and your own review stays the boundary, since agents work with your own gh account and keys |
Guard rules › What the guard is and is not |
| 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 | Skills and plugins |
| 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.
- 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.
- 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), in parallel lanes with their own files and time.
- 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(skills of the same name in Codex). - Skills:
using-devkit,handoff,communicating,working-efficiently,crew,workspace,delivery,release-policy,testing,cicd,learning-loop,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, plain 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.
- Guard: a pre-tool hook that blocks what wastes time or disk and holds irreversible actions for your grant, and explains the right way in one sentence. It is a seatbelt, not a sandbox: keep reviewing what agents 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.
The ideas behind it are in docs/concepts.md.
| 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, completion, Docker environment) |
tools/brand/ |
Renders devkit's icon and banners from the Firefly brand elements |
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, 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, the guard, the status block, and the background sync |
| Teams and machines | Work items and locks, reasons, and history, versioned plans, session logs, presence, merge rules |
| 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, and guided or automatic decisions |
| Continuity | What a session keeps through compaction, resume, and /clear, and dev session |
| Progress and communication | dev progress, the time model and ETA, notifications, 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, 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, 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, and dev ci watch 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, known pitfalls, prevention by automation, dev sleep |
| Scheduled jobs and the audit trail | The background jobs and their schedules, logs, and journal; the audit trail |
| Guard rules | Everything the guard blocks, and why |
| Diagrams | dev diagram and the diagram design rules |
| 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.