Guide

How to work in Project Coldfall.

What the app is for, how to set it up in a few minutes, and what a normal day with it looks like.

The idea

If you use Claude Code, Codex or another agent in the terminal, you probably have a pile of tabs: one for the app you're building, one for research, one you forgot about. Each one starts from scratch when you close it, and you only find out one of them finished, or is waiting on a yes, when you happen to click on it.

Each desk runs the vendor's own tool, the same claude or codex you already use, in a real terminal. Your logins, settings, memory files and hooks all work exactly as they do now. Coldfall doesn't replace your agents; it organizes them.

It works with Claude Code, Codex, Antigravity (Google's, for Google AI Pro and Ultra plans), GitHub Copilot CLI, Grok, and Ollama for models that run on your own Mac.

Your first ten minutes

1. Install it. Download it, drag it into Applications, and let macOS open it the first time (the install steps show how).
2. Open it. The Welcome screen lists the agents it found on your Mac and makes a desk for each one. Nothing starts on its own: each desk starts when you pick it. If you don't have any yet, it shows how to install one, with a Copy button.
3. Click a desk, then Start. A desk that isn't running shows a Start button first (Return works too), so a stray click never starts anything. Its agent then runs in the middle of the window; work in it the way you always do. Settings ▸ Desks turns the button off if you'd rather start with one click.
4. Click another desk, then come back. Nothing was lost. Desks keep running while you look at something else.

Set up your desks

The desks Welcome makes are a start. The app gets useful when you make one for each job you keep coming back to.

Make a desk

Open Settings (⌘,) and go to Desks. Give it a name, pick the agent, choose the folder it works in, then click Add / Update and Save. Two optional fields there: a second Claude account, and a weekly budget in dollars. Agents you've already defined, like Claude Code subagents, are listed there too, one click each.

Or edit the file

Every desk lives in one plain text file, ~/.config/coldfall/desks.toml. Edit it in any editor, or let an agent edit it, and the app picks up the change within a second.

# one desk per ongoing job
[desk.api]
runtime = "claude"
cwd = "~/code/api"
group = "work"

[desk.review]
runtime = "codex"
cwd = "~/code/api"
group = "work"

[desk.research]
runtime = "claude"
agent = "researcher"        # a Claude Code subagent you've defined
cwd = "~/notes"
budget = 50                 # dollars a week; the row turns red when it's over

Good habits

• A desk per job, not per task. "The API", "the newsletter", "my budget". Start a new conversation inside a desk when you want a clean slate; keep the desk.
• Point each desk at its own folder. The agent reads and writes there, and its memory files there apply.
• Group them. Desks with the same group fold together. Drag desks and whole groups into the order you like, or right-click and sort A to Z.
• Pin the ones you live in. Right-click, Pin to Top. A pinned desk stays at the very top of the rail, above everything else, and cmd-1 goes to the first one.
• Let finished desks come to you. When a desk is waiting on you it turns green and rises to the top, under your pinned desks, then goes back to its place once you've looked at it. Rows only move while the pointer is away from the rail, so nothing jumps under a click. Right-click the rail to turn Move Ready Desks to Top off.
• Hide what you're not using. Right-click, Hide Desk. It stays in the file and comes back with one click.

Two Claude plans

Give a desk account = "~/.claude-second", or fill in account in Settings. That desk runs Claude on a second login, kept apart from your first; its first start asks you to sign in. After that:

• The rail and the meter name it claude-second, after its folder, so you can see which plan has room this week.
• It picks its conversation back up like any other Claude desk.
• Agent mail can ask it. A desk on your first plan can hand a question to the second, and the second answers read-only, on its own quota.

A normal day

Hand a desk a job, move on to another desk, and let Coldfall tell you when to come back.

• A green check on a desk means it finished while you were looking at something else, and its screen changed. It might want an answer, or it's just done. Its row also moves up to the top of the list, under the green line, until you've looked at it.
• Make green exact. Settings, Agents, Let agents say when they're done. Claude Code and Codex then tell Coldfall when a desk finishes or needs you, so a desk turns green on the agent's word rather than a guess from its output. It writes one line to a file on your Mac and sends nothing. Codex asks you to trust the new hook once: run /hooks in a Codex desk.
• The green line at the top names every waiting desk, oldest first. Click it, or press ⌘0, to go to the one that's waited longest. The × clears it without visiting them.
• Jump around with ⌘1 to ⌘9 for your first nine desks, or ⌘P to find any desk or file by a few letters.
• Need a plain shell? ⌘D splits one in beside the agent, in the same desk and folder. For a shell of its own in the list, ⌘N makes a new shell desk.
• Files your agents write open in the reader on the right, with Markdown and PDFs shown properly.
• Done with a desk for now? Right-click, Stop Desk. That frees its memory, and the desk picks up its conversation right where it was when you click it again. More in Stopping and coming back.
• Not sure how to ask? Write a prompt… at the top right of the terminal, or in the Edit menu, walks you through four questions: what you want, what the agent should know, the boundaries, and what a good result looks like. It builds a draft you can edit and copy into any agent. Nothing is sent and no model is called.
• When one of your agents updates, the top of the desk list says so, like "Claude Code updated to 2.1.280", with a What's New button that opens the vendor's own release notes.

Second opinions

Different models catch different mistakes. Agent mail lets one of your agents ask another about the work in its folder.

1. In the desk whose work you want checked, press ⇧⌘M for Agent Mail.
2. Pick who should answer, say Codex if you've been working in Claude, write the question, and click Send.
3. The answer comes back in the thread. The whole exchange is saved as a plain text file, so the desk's agent can read it too.

The answering agent is kept read-only by its vendor's own setting for Claude and Codex, so it can look at your files but not change them. For other agents it's asked to stay read-only, and the panel tells you that.

Fan out, from the same panel, asks one question across several project folders at once, and checks the cost against your weekly limit before it runs.

Watch your usage

The strip along the bottom shows how much of each plan you've used this week, side by side. When one is running hot and another has room, it says so. Click it, or press ⇧⌘U, for the full picture, in three tabs:

• Plans: what's left of each plan this week, and when it resets.
• This week: where the tokens went, by agent, by desk and by day.
• Where it went: why. How much came from the cache, which models did the work, what each desk carries on every turn, and a short list of what to change, written from your own numbers.

Codex and Copilot usage is read automatically. For Claude's weekly and five-hour limits, turn on the recorder in Settings; it's one click. Each desk's row also shows how much memory it's using, so the heavy one is easy to spot.

Spend less

Every message to an agent re-sends the whole conversation so far. That's what makes a desk remember, and it's also why a long conversation gets expensive. Three habits keep it in check, and Where it went shows which ones matter for you:

• Keep sittings together. On Claude, a conversation you came back to within the hour is read from the cache for a small fraction of the price. After a longer break the first message sends all of it again, and rebuilding the cache costs 20 to 40 times what a warm turn does; Coldfall shows the dollar figure for that conversation before you pick it up. Where it went counts how often that happened this week.
• Hand the messy jobs to a subagent. Big searches, long logs and reading many files pour thousands of lines into a conversation, and they ride along on every later turn. Ask the agent to use a subagent for them: it does the reading in its own conversation and only the answer comes back.
• Use the smaller model for routine work. Where it went shows what the week would have cost on a smaller model. Set model on the desks that don't need the big one.

Give a busy desk a budget. In Settings ▸ Desks, or budget = 50 in desks.toml, a Claude desk gets a weekly dollar budget. Its row turns orange when it's close and red when it's over, so you notice which desk is eating the week. Nothing is stopped; it's a warning, not a lock.

Screenshots are worth a thought too: each one stays in the conversation and is sent again on every turn after it. A page's text usually answers the question for far less.

Stopping and coming back

Stopping a desk never loses anything. When you open it again, it picks up its conversation right where it was. That's the default, and it stays that way unless you choose otherwise.

Wrap Up, for a finished topic

When a desk's conversation is big, Stop Desk also offers Wrap Up & Stop. The desk saves what's worth keeping to its own notes, the way it normally would, and Coldfall shows you when it's done so you can check before it stops. Next time you open the desk, a clean conversation is the suggestion, since the important parts are already saved.

Coming back to a big conversation

If a big conversation has sat for more than an hour, opening its desk asks whether to pick up where you left off or start clean. Picking up is the default. A clean start keeps the desk's name, folder, instructions and memory files; only what was said in the chat stays behind, in the old conversation.

Nothing is ever deleted. To go back to an older conversation, type /resume in the desk and pick it.

Don't want to be asked? Tick "Don't ask" in the question itself, right-click a desk and untick Ask Before Reopening a Big Conversation, or turn it off for every desk in Settings ▸ Desks.

Keep desks lean

Plugins, skills and MCP servers pile up, and some run on every session or every tool call. Right-click a desk and choose What This Desk Has to see what it loads: servers, skills, plugins and hooks, read from the vendor's own files. Anything new since you last looked is marked, and the desk's row says "2 new" until you've checked.

If a Claude or Codex desk doesn't need a server, right-click, MCP Servers, and switch it off for that desk only.

Shortcuts

Right-click almost anything, a desk, a group, the green line, for more.

If you want out

Coldfall runs your agents; it never replaces them. So leaving costs nothing: Claude Code, Codex and the rest keep their logins, conversations, settings, hooks and memory files, and work from a plain terminal exactly as before. Desks that run your own script are your script.

Everything Coldfall has of its own is in two folders, plus one thing it changes elsewhere if you turned on live Claude limits: statusLine in that account's settings.json, which it points at its own recorder (that recorder still runs whatever statusline you had).

In the app, Settings ▸ General ▸ Remove Project Coldfall's Files… shows you exactly what it would delete and how big it is, puts the statusline back the way it was, and deletes the two folders. Then quit and drag the app to the Trash. By hand it's the same three steps:

rm -rf ~/.config/coldfall ~/.local/share/coldfall
# and if you turned on live limits, point statusLine in
# ~/.claude/settings.json back at your own command, or delete the line

Your desk list goes with it, so copy ~/.config/coldfall/desks.toml first if you might come back.

Every desk name and folder in this guide is made up.