Torch

A quick look

Plain torch shows every project, with how many tasks need you and how many are next.

▲ torch  3 projects · 4 tasks need you

       project         you  next   where
  ST   Studio Notes      2     3   ~/Projects/studio-notes
  GA   Garden Planner    1     3   ~/Projects/garden-planner
  RE   Reading Club      1     1   ~/Projects/reading-club

  next: torch needs  ·  torch <project>  ·  torch <task ID>  ·  torch help

torch needs lists everything waiting on you across every project, so you can clear decisions in one go.

▲ 4 need you

  ◐ ST-001  Choose the launch headline  41m · Studio Notes
  ● ST-002  Approve the welcome email   3h · Studio Notes
  ● RE-001  Choose the November book    10h · Reading Club
  ● GA-001  Pick the spring seed list   1d · Garden Planner

A project opens by its code or any part of its name, with your tasks at the top and what the agents are working on below.

▲ Studio Notes  ST · ~/Projects/studio-notes
  goal  A small weekly newsletter about making things.

needs you
  ◐ ST-001  Choose the launch headline     41m
  ● ST-002  Approve the welcome email      3h
others
  ● ST-003  Draft the first issue outline  Codex · 26m
  ◐ ST-006  Add the welcome image          Codex · 4h
  ● ST-004  Finish the signup page         Claude · 5h
  ◐ ST-005  Get feedback from Ari          Ari · 2d
2 backlog · 2 done

A task ID shows the task itself, why it exists, what's done, what's next and the last notes an agent left behind.

◐ waiting  Choose the launch headline  ST-001 · Mina · 41m

  why    The signup page and the first issue both lead with it.
  done   Two options drafted: "Small work, shared often" and "Notes …
  next   Mina picks one; Claude updates the signup page.

  ── checkpoints ──
  41m  Claude     Changed: drafted two headline options. Evidence: laun…

  full record: torch task show ST-001

Try it

This terminal has the same example projects, with output captured from the real CLI. Type a command or pick one below.

Example data: Mina's three projects. Type help for ideas.

Your agents do the rest

You mostly talk to your agent, and the skills tell it what to do with Torch. They work the same in Codex and Claude Code.

torch-start

“Set up Torch here.”

torch-list

“What needs me?”

torch-plan

“Plan the next steps for this project.”

torch-work

“Work on ST-003.”

torch-tidy

“Tidy this project’s tasks.”

Install

# Node 22 or newer
git clone https://github.com/cs-jason/torch
cd torch && bun install && bun link
torch owner "Your name"
torch skills install

Then open a project folder and ask your agent to use torch-start. The README covers the file format and every command.

How it got here

Torch started because I kept explaining the same project over and over. I usually have a few agents running at once, and every new session starts with no memory, so I'd paste in the same background and decisions each time.

The first version was a local web app with lanes for Attention, Next, Waiting on people, Blocked, Backlog and Completed. It looked calm and I enjoyed building it.

In practice nobody opened it. I checked it every now and then, but the agents never did, since they work with files and not web pages. The dashboard had become a second copy of the truth that only I could see.

Records grew until they were noise

Each task had its own page, and agents kept adding to it. Every session appended a summary of what it did, until one task passed 6,000 words and every new agent had to read all of it before starting.

The fix was to keep the current state rather than the whole history. Older text now moves to a history folder and the task keeps only what's true today, so that 6,000-word task is down to 239 words without losing anything.

Trying the cloud, then rolling it back

For a while I wanted Torch on my phone, so I set up a hosted reader, a tunnel, access rules and sync between machines. It mostly worked, but it also meant another server to keep alive and another place for things to drift out of sync.

Torch is local first now. The files sit next to the work, and Git or iCloud already handle moving files between machines, so Torch doesn't need to.

Fewer states

Version 0 had six statuses and a priority field. Agents weren't good at guessing priority, and the status already said most of it anyway. If something is next it matters, and if it matters less it goes to the backlog.

• Attention
• Blocked
• Priority
• ● next
• ◐ waiting
• ○ backlog
• ✓ done

Attention became a question instead of a status. A task needs you when it's yours and it's next or waiting, and Torch works that out on its own, so nobody has to remember to set a flag.

Limits any model can follow

The strongest models tidy up after themselves, but not every model does. I wanted Torch to stay lean no matter which one was writing, so the limits live in the tool rather than in a prompt. Anything over a limit is refused, with a message saying what to shorten.

Every checkpoint follows the same shape (what changed, the evidence and what's next), which keeps it readable at a glance and leaves little room for a weaker model to ramble.

Rules in one place

The instructions used to be copied into every project, and over time the copies drifted apart. Now torch help rules is the single source, and each project's AGENTS.md simply points to it.

From dashboard to terminal

What I actually wanted from the dashboard was a quick glance, so the views moved into the terminal where I already spend my day. I tried small progress bars in the project table first, but they read as clutter, and two plain numbers did the job better. The colour is only there for people, so agents and scripts get plain text.

Where it is now

Torch runs all of my own projects every day, and it's now open source under the MIT licence. Most of the work turned out to be taking things away, a web app, a server, two statuses, a priority field and thousands of words, and what's left is small enough for any agent to learn in a single read.

If you try it, I'd love to hear how it goes on GitHub.