duskfleet
v0.5.0
Published
A fleet of agents for your own machine
Maintainers
Readme
Duskfleet
Run, record and schedule unattended Claude Code agents on your local projects.
Your agents sail at dusk.
A fleet of agents for your own machine.
Website: duskfleet.com
Quick start · First scheduled run · From source · Before / after · How it works · What you get · Commands · FAQ · Status and roadmap · Documentation · Contributing · License · Star history · Website
Who it is for: people who already run Claude Code on their own projects and want those runs
unattended, scheduled and recorded, on their own machine. Duskfleet runs claude -p against a
project on your disk and keeps a record of what happened.
- Local, no account, no cloud: everything runs on your machine with your own Claude Code login; there is no service in between.
- Every run recorded: events, tool calls, permission denials, tokens and cost land in a local SQLite database, plus a JSONL log per run.
- Cron schedules and a dashboard: schedules fire from a local process, and a dashboard on localhost shows runs, schedules and agents. It never writes runs; it edits agent files, schedules and the editable settings keys.
Quick start
Requirements: a supported platform (below), Node.js 24+ (built-in node:sqlite, no native
addons; .nvmrc pins it, and an older Node gets Duskfleet needs Node 24 or newer; you have
vX.Y.Z), and Claude Code installed and
logged in for the user that runs Duskfleet (Duskfleet does not manage authentication).
Only runs need the login: before it, init, doctor, agents create, the other read-only
commands and the dashboard already work, and init ends with the command to log in.
Platform support
| Platform | Status | Notes |
|---|---|---|
| macOS | Supported | Developed and run daily by the maintainers; install-service uses launchd |
| Linux | Supported | install-service uses a systemd user unit |
| Windows | Experimental | Implemented (install-service registers a Task Scheduler logon task) but not run by the maintainers. The service log is data/logs/serve.log, the task XML is kept under %LOCALAPPDATA%\Duskfleet. Help verify it with the Windows test plan |
This table is the one place that states platform support; other pages link here.
Nothing to clone: the CLI comes from npm.
npx duskfleet init # checks Node and the Claude Code login, creates the config and data directories
npx duskfleet doctor # Claude binary, version, where config and data liveInstall only from the duskfleet/duskfleet repository
on GitHub or the duskfleet package on npm. No other
source is official.
init creates the user-level config and data directories (~/.config/duskfleet and
~/.local/share/duskfleet on Linux and macOS, Configuration) and, on a
terminal, offers to register the MCP server in Claude Code or Claude Desktop; --yes skips the
questions. See init.
Duskfleet ships no starter agent: create your first one, on the cheapest model. agents create
writes it to the data directory's agents/fixer.md with safe defaults: a $0.50 budget, no
permission prompts (dontAsk), file tools plus the common test commands, 10 minutes.
npx duskfleet agents create fixer --model haiku -- "You fix the failing test in this project. Run the tests, read the failure, change the minimum code, run them again. No git, no installs."Then try it on a small throwaway project of your own (anything with a failing test will do):
npx duskfleet run --project /abs/path/to/scratch-project --agent fixer -- "Fix the failing test"
npx duskfleet runs
npx duskfleet dashboard # installs the dashboard on first use, opens http://localhost:4777run and runs print a human view; scripts add --json (CLI output).
Before running agents unattended, review the security boundaries and set
allowed_project_roots to the project directories you intend to expose.
[!WARNING] Real runs cost money. An agent without an explicit
modeluses the Claude Code default; sethaikuorsonnetwhile experimenting.
Then register the MCP server in Claude Code or Claude Desktop, if init did not:
npx duskfleet mcp register --target claude-code --dry-run shows the change, the same command
without --dry-run makes it (--target claude-desktop for the desktop app). Ask the assistant
to create agents, start runs and set up schedules: see MCP server.
To keep schedules firing with Claude Desktop closed, register the scheduler as a per-user
service once. The service needs a global install, not npx's temporary cache:
npm i -g duskfleet, then duskfleet install-service
(Schedules).
From here to a schedule that fires on its own, step by step in about ten minutes: Your first scheduled run.
From source
For contributors, or to run an unreleased main:
git clone https://github.com/duskfleet/duskfleet.git
cd duskfleet
npm install
npm run build
npm run cli -- init --yesIn a clone every npx duskfleet <command> above is npm run cli -- <command>, and the dashboard
is npm run web; init finds the repo's config/ and leaves it as it is, and the data lands in
the clone's data/ (git-ignored). Setup, rules and checks: CONTRIBUTING.md.
Before / after
Before: claude -p started by hand or from a crontab, the output in a terminal, and no
record of what happened overnight.
After: agents are Markdown files (Agents); cron schedules keep a busy tick as one pending fire, retried until the agent is free or the next occurrence comes, and never catch up after sleep (Schedules); every event, tool call, permission denial, token and dollar lands in SQLite plus a JSONL log per run (What a run records); and in the dashboard a run that hit a permission denial is "needs review", never green (Needs review).
How it works
Every run starts as a call to RunManager.startRun, from a chat, the CLI or a cron schedule.
The child is Claude Code in your project; everything it does is recorded.
%%{init: {"flowchart": {"wrappingWidth": 420}}}%%
flowchart TB
subgraph entry ["1 · Entry points"]
chat["Chat host<br/>run_agent over MCP"]
cli["CLI<br/>duskfleet run"]
sched["Scheduler tick<br/>due cron"]
end
subgraph rm ["2 · RunManager"]
guards["Concurrency guards: busy is refused, a scheduled tick is deferred, never queued<br/>pass: run row recorded (pending)"]
end
subgraph child ["3 · Claude Code child"]
claude["claude -p --output-format stream-json<br/>in the target project, allow-lists only, no prompts"]
end
subgraph rec ["4 · What gets recorded, from the stream-json events"]
db[("SQLite<br/>runs, run_agents")]
logs["data/logs/<br/>raw stream, patch"]
end
chat --> guards
cli --> guards
sched --> guards
guards --> claude
claude --> db
claude --> logsWhatever the entry point, the request lands in RunManager, the only thing that creates runs and
changes their status. Its concurrency guards run first (one run per project directory and one per
agent by default): a busy guard refuses, nothing is ever queued, and a schedule keeps that tick as its
one pending fire until the next cron occurrence. When the guards pass the run row is recorded and the
executor spawns Claude Code in the target project with the agent's allow-lists, model and budget, no
permission prompts and no MCP servers unless the agent opts in. Every JSON event the child prints is
parsed as it arrives: the row in SQLite holds status, timings, tokens, cost, tool calls, permission
denials and the termination reason, one run_agents row per subagent, while the raw stream and the
patch of what changed land in data/logs/. The dashboard only reads that database.
A run moves through these states; the transitions below are the only ones allowed:
stateDiagram-v2
direction LR
[*] --> pending : startRun, guards pass
pending --> running : claude spawned
pending --> failed : spawn error / orphaned
running --> completed : result event
running --> cancelled : cancel_run
running --> failed : error / non-zero exit / orphaned
completed --> [*]
cancelled --> [*]
failed --> [*]"Needs review" is not a status but how the dashboard shows a completed run that hit a permission denial, a timeout, an exhausted budget or did nothing: amber, never plain green.
You describe what should happen in config/ (agents, projects) and in schedules. Duskfleet
runs claude -p unattended with a target project as working directory, owns the unattended
envelope (permissions, allow-lists, budget, MCP) and records what happened. A run end to end,
with diagrams: How it works.
What you get
| | |
|---|---|
| Agents | Markdown files: a persona of your own, or a link to an agent the project already defines in .claude/agents/. Agents |
| Runs | Every event, tool call, permission denial, token and dollar, in SQLite and a JSONL log per run. CLI |
| Schedules | Cron schedules that defer a busy tick as one pending fire, retried until the agent is free or the next occurrence; no queue, no catch-up after sleep. Schedules |
| Dashboard | Runs with cost, timeline and issues; a run that hit a permission denial is "needs review", never green. Dashboard |
| MCP tools | 19 tools to create agents, start and inspect runs and manage schedules from a chat. MCP server |
| CLI | The same operations from a terminal, plus serve and install-service for the scheduler. CLI |
| Harnesses | One run path, one adapter per agent CLI: Claude Code today, Codex and Copilot planned; an agent field a CLI cannot honour is refused, never approximated. Harnesses |
Commands
Each command is npx duskfleet <command> (duskfleet <command> after npm i -g duskfleet, or
npm run cli -- <command> in a clone), and every CLI command answers --help; the last two
rows are npm scripts of a clone. The full reference, with every
option: CLI.
| Command | What it does |
|---|---|
| doctor | Claude binary and version, where config and data live, scheduler state. CLI |
| run --project <id or path> --agent <id> [--model <m>] [--no-wait] -- "<task>" | Starts one run and prints its record. CLI |
| runs | Lists recorded runs, with needsReview and the reasons. CLI |
| run-info <run_id> [--events] | One run in full, subagents included; --events adds the timeline. CLI |
| agents, projects, schedules | Lists agents, registered projects and schedules. CLI |
| schedules run-now <id or name> | Asks the scheduler to fire a schedule on its next tick. Schedules, CLI |
| serve | The long-running scheduler process. Schedules |
| install-service [--print], uninstall-service | Registers serve as a per-user service (launchd, systemd, Task Scheduler), or removes it. Schedules |
| tools | The MCP tool catalogue. CLI, MCP server |
| repair-subagents | Backfills subagent rows of finished runs from their logs. CLI |
| npm run web | The dashboard from a clone, on http://localhost:4777. Dashboard |
| npm run build, npm test, npm run check | Build, tests, and the full CI gate, in a clone. Development |
FAQ
Why local and not a cloud service? Your projects and your Claude Code login already live on
your machine, so the agents sail from there: Duskfleet runs claude -p in the project directory
and keeps the record in a local SQLite file, with no account and nothing in between. How it works
What does a night of agents cost? Whatever Claude Code bills for the runs. Duskfleet records
tokens and costUsd per run, and marks subscription costs "reported, not billed". An agent
without a model uses the Claude Code default: set haiku or sonnet while experimenting.
What a run records
What happens when a run goes wrong? It is never green: a permission denial, a timeout, an
exhausted budget or an empty run makes it "needs review", and a run whose process died is marked
orphaned instead of staying running forever. The fixes are one page away.
Needs review, Troubleshooting
Do schedules run with Claude Desktop closed? Only if something else holds the scheduler:
serve, registered once as a per-user service with install-service. With the MCP server
alone, schedules stop when the host closes. Who ticks
Does Duskfleet handle Claude authentication? No. Claude Code must be installed and logged in
for the user that runs Duskfleet; a run without a login fails with auth_required and the
command to fix it. Quick start, CLI
Which OS? macOS and Linux. Windows service support exists (a Task Scheduler task) but has not been exercised by the maintainers. Platform support, Who ticks
Status and roadmap
Working today: agents, runs, scheduler, dashboard, 19 MCP tools. On the roadmap: deterministic and LLM evals as post-run hooks, metrics, Git integration.
Formerly Gab Factory (renamed 2026-10-11); an existing data/gabfactory.db is adopted on first
start.
Documentation
| Page | Contents |
|---|---|
| Your first scheduled run | About ten minutes from npx duskfleet init to a scheduled haiku run on the dashboard and the service that keeps it firing |
| How it works | A run end to end, with diagrams: entry points, RunManager, the Claude Code child, what gets recorded, run lifecycle |
| Configuration | duskfleet.yaml, projects registry, concurrency limits, environment variables |
| Agents | The two agent kinds (own, link), frontmatter, permission modes in unattended runs, project binding, MCP servers inside runs |
| Schedules | Cron schedules, who ticks, running unattended as a service, busy and kill-switch policies |
| MCP server | Registering in Claude Desktop and Claude Code, the tool catalogue, a typical conversation |
| CLI | Commands, and what a run records |
| Dashboard | The five views and what "needs review" means |
| Security | Process, filesystem, permissions, dashboard and local run-data boundaries |
| Development | Repository layout, code map, build and tests, extending |
| Troubleshooting | Stuck runs, denials, orphaned runs, doctor failures |
| Windows test plan | Step-by-step checks to verify the experimental Windows support, with a results column |
Guides:
| Guide | Contents |
|---|---|
| Run Claude Code on a schedule on your own machine | claude -p from cron, launchd and systemd, the failure modes unattended (PATH and login, permission prompts, overlapping runs, silent failures, sleep) and what Duskfleet does about each |
| Run a development loop with agents | A developer and a reviewer agent on schedules, coordinated by flow: labels on GitHub issues and PRs: labels, agent files, schedules, the PR gate, what humans keep doing |
Contributing
Setup, rules and good first issues: CONTRIBUTING.md.
