Skip to content
fireflysoftwaresolutionsPublic

About

One workspace for developers, Claude Code and Codex: the dev CLI, plugins and agent rules, guard hooks, a crew of specialist agents, blast-radius testing, CI/CD audits, handoff and a live dashboard.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

devkit: Every repo in its place. Every agent on the same page. By Firefly Software Solutions Inc.

devkit

Latest release CI License: Apache 2.0 Python 3.9 or later macOS on Apple silicon For Claude Code and Codex

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

Why devkit

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

Install

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 passes

The 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.sh

Pass 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.

A quick tour

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
The devkit dashboard's Now view: the headline says 2 things need you, because a run is paused until you answer the decision D1@7f3a and CI failed on a branch. On the left, the Needs you queue: the decision with an amber bar, its options and the words to type, the failed CI run with the command to copy, a pull request with changes requested, and a Housekeeping row of 5 items. On the right, two running runs, each with a landing strip of its steps and when it lands. Below, the Sessions on this Mac section, a line about a branch that is only on this Mac, and what finished since yesterday.

All commands are in docs/commands.md.

From plan to operate

From plan to operate: plan with dev plan new and Superpowers; track the task with dev task; build with dev progress and the required skills; pass the local test gate with dev ci --run and dev sec scan; open the PR with dev pr create and the communicating templates; integrate on one branch and push once with dev push; release by the recorded policy with dev release and the release-policy skill; follow CI with dev ci status; deploy through a tag and its pipeline; hand off with the handoff skill and dev lesson.

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.

Features

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

For your agents

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 status in 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 --wait wakes it for each crew question, answer, decision, ready step, and CI result, and a crew member waits for its own answer with dev 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, and diagrams, 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 devkit itself fails

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.

How it fits together

How devkit fits together: the devkit repo installs rules, the devkit plugin, and hooks into Claude Code (CLI and Desktop) and Codex (CLI and the ChatGPT app); the agents work in your repositories and exchange context, session records, tasks, and lessons with the private handoff repo, which a sync after every delivery event and the scheduled launchd jobs keep current; repositories and the handoff repo are pushed to GitHub, and the dashboard and overview read the handoff repo.

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.

What's inside

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 .)

Documentation

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

Credits and license

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.

About

One workspace for developers, Claude Code and Codex: the dev CLI, plugins and agent rules, guard hooks, a crew of specialist agents, blast-radius testing, CI/CD audits, handoff and a live dashboard.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages