Getting started

Blink is project management for coding agents. Your agents write the plan down as they work, one markdown file per milestone, task, decision and risk, and Blink turns that pile of markdown into a live picture of every project you have.

Three parts. A set of skills that blink init installs into your repository, so the agent does the project management itself instead of you keeping a board. A file format that lives in your repo and in git, which is the memory. A local dashboard that watches those files and renders them as they change.

Blink itself never writes your code. It plans with you, records what was decided, validates the record and shows you where everything stands. Your agents do the work the way they do it today.

One global install. Blink ships as a native binary per platform, so nothing needs a Node runtime to run it.

Run this from inside the project you want tracked.

It writes blink.json at the root, a .blink content directory holding example entities to copy from, a SCHEMA.md field reference, and the agent skills under .claude/skills. It also adds a short instruction block to CLAUDE.md and to AGENTS.md, creating either file if it is not there. The examples are written only into directories that have no markdown in them yet, so a project with thirty real tasks never gains a fake one.

init is the only command that scaffolds your repository. It writes only inside the directory you point at, it never overwrites a file you have edited, it prints what it did to every file it touched, and it ends by running the validator over the result.

Run it again after upgrading Blink. The skills and SCHEMA.md carry a version stamp, so init upgrades the ones it wrote and you have not touched, reports anything you have edited as kept, and writes nothing at all when the stamps already match. blink.json, project.md and the examples are yours rather than Blink's, so a later run reports them as already there and leaves them alone.

The server binds 127.0.0.1 on port 7777, walking upward if that port is taken, and stays in the foreground until Ctrl+C. Changes arrive over a WebSocket as your agents write the files, so nothing needs reloading. It is dark theme only.

A bare blink gives you the fleet: every registered project on one screen, with totals across all of them and a card each showing what needs attention, what is in flight right now and how long since anything changed. A project that has gone quiet is visible as quiet. Click into one for its own board, timeline, agent workload, decisions, risks and git activity.

The dashboard is deliberately read-only. Nothing in the browser can edit a file. It is local too: Blink binds loopback and never 0.0.0.0, and it refuses any request whose Host is not a loopback address. What that does not stop is everyone else on the same machine, which is what blink set-password is for on a shared box or a build agent.

Running it in the background

Exactly one server runs at a time and every command is idempotent, so a second start reports the one already running and a stop with nothing to stop says so and exits 0. Set BLINK_NO_OPEN=1 to keep any command from opening a browser.

This part is talking rather than typing. The skills are sitting in your repository now, so your agent already has them.

The slash commands below are Claude Code skills, installed under .claude/skills, so they will not fire in another agent. The contract still reaches one: init writes the same rules into AGENTS.md, and what a different agent misses is the guided session, not the format.

It runs the validator, counts what is already in the tracker, and loads exactly one procedure: an interview when the tracker is empty and there is no code yet, a survey of the repository when there is code but no plan, milestone planning when you ask it to plan, and a read-only status summary when you only want to know where things stand. It reads before it asks, so it never asks what the repository already answers. Questions come one at a time and nothing is written until you confirm.

Planning ends with milestones on disk and a confirmed set of task files, each one at backlog or planned with its milestone named. That set is what the next session picks up from, and it is where this on-ramp ends.

A PLAN.md, a folder of ADRs, a pile of TODOs. Setup surveys what you already have, shows you the whole findings table, and converts it only once you agree. It audits a Blink project that is already wired up too, and tells you what is out of date.

The other skills

• blink:tracking is always on and you never invoke it. It is the contract every agent follows: write the task before the work, move it to in_progress when starting, done when it ships, and a decision file when a real choice gets made.
• blink:sync compares the tracker against git history, reports where they disagree, and repairs only what you confirm.
• blink:pause parks a task with a recorded reason, and blink:resume brings it back and clears the reason.
• blink:design interviews you once about design context, then iterates on a prototype served locally. Nothing is accepted without you looking at it.

One markdown file per entity, in your repository, in git. The YAML frontmatter is state and the body is the thinking. A teammate who has never installed Blink can read the whole tracker with cat, and a change to the plan arrives in a pull request like any other change.

• The directory decides the type. Tasks, milestones, decisions, risks and docs each get one, and project.md sits at the top of the content directory.
• A filename starts with the id, usually followed by a hyphen and a slug. A doc's filename is exactly its id plus .md.
• The frontmatter id is authoritative. A filename that disagrees with it is a warning and the file still loads.
• References only ever point forward. A task names its milestone; a milestone never lists its tasks. Every reverse index is computed, so moving a task touches exactly one file and two agents writing at once do not collide.
• Ids are timestamps rather than counters, which is why blink id t prints one instead of you picking it. Counting up from the highest existing id is how two clones allocate the same one.

Progress is never written into a file. It is done divided by total minus dropped, computed every time it is read, so it cannot go stale.

blink.json at the project root is what makes a directory a Blink project. It names the project and its id, and it can move the content directory somewhere other than .blink, set the color the project is drawn in on the dashboard, and turn the git feed or worktree scanning off. There is no settings screen, so a project's setup travels with its repo.

Every type has a fixed status vocabulary and validation enforces it. There are no per-project enums, and the vocabularies deliberately do not overlap: in_progress is a task status, and a milestone being worked on is active.

• Task: backlog, planned, in_progress, blocked, paused, done, dropped.
• Milestone: planned, active, done, dropped.
• Decision: proposed, accepted, superseded.
• Risk: open, mitigated, accepted, closed. Severity is required and is one of low, medium or high.
• Doc: draft, active, superseded. Type is required and is one of brainstorm, note, research or spec.
• Project: active, paused, done, archived.

How a task moves

backlog to planned to in_progress to done, with three exits. dropped is cancelled and terminal. blocked needs blocked_by naming the risk or task holding it up. paused needs paused_reason saying why the hold exists. Both of those are validation errors without their companion field, because a state nobody can act on is worse than no state at all.

The file is created at backlog while the work is still being planned, not when someone starts it. Everything else depends on that one habit: a task written after the work is a summary, and a task written before it is a plan that is still on disk when the session dies halfway through.

Nothing is ever deleted. Abandoned work becomes dropped, which keeps the history and takes it out of the progress denominator. The board carries a column for every task status except that one.

Two things go wrong and they need different tools. Either a file is wrong on its own terms, or the files and git disagree about what happened.

Exit 0 means clean and exit 1 means errors. Warnings alone still exit 0, which is what makes this usable as a CI gate: a filename that drifted from its id never fails your build, an invented status always does. Exit 2 means the project could not be read at all, which is usually a missing or malformed blink.json.

Errors are things like a status outside its enum, a missing id or title, a date that is not a real calendar day, blocked with nothing in blocked_by, or two files of the same type sharing an id. Warnings are the softer kind: a filename that does not match its id, a stray markdown file loose in the content directory, a reference pointing at an id that does not exist. Nothing is ever dropped silently, and a file that fails its schema is still listed with the reason.

When a session dies mid-task

The tracker says a task is in flight, git says it shipped a week ago. Do not fix that by eye.

Every finding carries a confidence, because the two kinds are not the same claim. A task whose creating commit already said done is a contradiction between two records that both exist. A task sitting at in_progress for two weeks might have shipped, stalled or been abandoned, and the repository cannot tell you which. Say did we forget to close anything, and blink:sync turns that report into repairs it asks you to confirm one at a time.

The exhaustive reference is the README that ships with the package, on npmjs.com/package/@weloin/blink. Every CLI command, every field, every dashboard view.

Two more references are already on your disk once blink init has run. SCHEMA.md inside the content directory is the field reference, written into your repo so agents and teammates have it without installing anything. The skills under .claude/skills are the workflow contract your agents actually follow, and they are readable prose rather than configuration.