@joshski/dust

Dust ✨

Flow state for AI coding agents.

Dust provides a CLI that agents use to systematically blaze through your backlog.

Quick Start

claude "install dust as per https://github.com/joshski/dust"

This works with other agents (codex, cursor, opencode, etc.) too. The agent will install dust and set up the .dust directory with an instruction in your AGENTS.md file.

Adding Tasks

Use your AI coding CLI (Claude Code, Codex, etc.) to add and refine tasks:

claude "add a task to refactor the auth module"

Ideas (.dust/ideas/) are backlog items you may or may not do later. Tasks (.dust/tasks/) are ready to work on now. Both are markdown files that agents and humans can read and edit.

Running Agents

Start an agent on a single task:

claude "implement the next task"

Or let dust run agents continuously in a sandbox with the loop command:

npx dust loop claude

This runs Claude Code in a ralph loop, picking up tasks until they are all done.

Codex Hook (Optional)

For Codex 0.125.0 or newer, you can replace the AGENTS.md instruction with a SessionStart hook that loads dust's instructions directly into the model's context — once per session, with no extra agent commands. Add this to ~/.codex/config.toml (or your project's Codex config):

[features]
codex_hooks = true

[[hooks.SessionStart]]
matcher = "^startup$"

[[hooks.SessionStart.hooks]]
type = "command"
command = "bunx dust codex hook"
statusMessage = "Loading dust agent instructions"

Learn More

Details live in the .dust/facts directory:

• Directory Structure — how .dust/ is organized
• Configuration — settings and quality checks
• CLI Commands — full command reference

Dust Bucket Worker

The dust bucket worker command runs a background worker that syncs agent sessions to dustbucket.com. This requires a dustbucket.com account (currently in private alpha, invite only).