Start here

junco is a harness-agnostic coding-agent worker: a local daemon that turns Markdown tickets and labeled GitHub issues into draft pull requests on your own machine, against any OpenAI-compatible inference endpoint or a hosted provider from its built-in catalog. Issues in. Pull requests out. Nothing runs anywhere but your hardware, under your own git and gh identity.

Prerequisites: Node 22.19 or newer, git, and an authenticated gh for the PR flows.

Sixty seconds to a running worker

npx @ironforgesoftware/junco

The first run opens the guided setup walkthrough: workspace, model endpoint, repo containment, the GitHub bridge, and an optional dedicated bot identity — safe defaults for everything else. It ends with a flight check and lands in the dashboard. From there, work arrives two ways:

junco submit my-task.md

— a Markdown ticket dropped into the queue, or a GitHub issue labeled junco: the daemon plans it as an editable issue comment, waits for your junco:approved, and opens a draft PR (the GitHub loop). Watch either from the dashboard:

junco

note — the daemon and every agent session run sandboxed and fail closed; nothing executes a raw issue without a reviewed plan and a verified approval. The security model is short and worth the read.

The map

How junco works: How a ticket moves from inbox to draft PR: queue, pipeline, loop guards, provider gate, spend cap, and outbox.
Security model: junco's trust boundaries: inbox, OS sandbox, approval gate, untrusted issue text, and what leaves the machine.
The GitHub loop: Label an issue junco: the daemon plans as an editable comment, executes on approval, and opens a draft PR.
Tickets & the inbox: Markdown tickets with YAML frontmatter: flavors, the plan shape that avoids loops, plan-lint, submission.
Assess: junco assess audits a repo, parks findings for review, and files only what a human confirms as GitHub issues.
Analyze: junco analyze investigates one issue read-only and parks a comment draft; only the confirmed post writes outward.
The dashboard: The fullscreen terminal UI: GITHUB and LOCAL modes, panes and key bindings, the command palette, repo watching.
Operations: Running the worker: daemon lifecycle, service files, health endpoints, the provider gate, spend, updates, recovery.
Bot account: A dedicated GitHub identity for the daemon: setup, per-repo grants, doctor checks, migration caveats.
CLI: Every junco command and subcommand: synopsis, flags, examples.
Configuration: Every config lever: type, default, live or restart, straight from junco's own registry.
Ticket schema: The frontmatter contract, field by field — junco schema rendered as a page.
Changelog: Release history for junco — every version's notable changes.
Tips, recipes & FAQ: Tips, recipes, and answers from running junco in the field.