ThreadBear - automated Codex thread management

Wrangle your threads.

Disorganized threads in Codex are unbearable. ThreadBear keeps every task classified, usefully titled, and safely archived — and spends zero model tokens on a heartbeat where nothing changed.

Pick ONE of the two installation options below.

Inside Codexpaws-off

Install ThreadBear by following https://github.com/ericlitman/threadbear/blob/main/INSTALL.md

In a terminalpaws-on

curl -fsSL https://threadbear.sh/install.sh | sh

macOS · installs to ~/.local/bin · no sudo · checksum-verified

a single Go binarya LaunchAgent, not a Codex automationno daemon of its own

Built to be boring where it counts.

A task manager that watches your agent all day can quietly cost more than the agent. ThreadBear makes the common case free and the expensive case bounded.

Deterministic first, model last

Most answers are already in local state: running, failed, automated, interrupted, or carrying the agent's own status footer. ThreadBear reads a read-only local index and decides without a model call, and every classification records how it was reached — runtime, structured_error, automation, interruption, footer, luna, or unknown — so provenance is auditable rather than implied.

An unchanged heartbeat costs nothing

The heartbeat is a macOS LaunchAgent, not a Codex automation, so an idle cycle exits against local state without spending a token. The prototype did the opposite — a long-lived Codex task that accumulated five million input tokens and replayed 92,000–138,000 of them on turns with nothing new to report. Deleting that cost model is why ThreadBear exists.

When judgment is required, it is one bounded call

Threads that survive the cascade are packed into the fewest calls that fit the model's context and sent to gpt-5.6-luna in a fresh, non-persisted session — no tools, no environment, no approvals, no history. Nothing accumulates, so nothing replays. Model and effort are configuration, not a release.

It only ever touches the title

A managed title is one canonical status emoji, a durable subject, and the current next action when there is one. A subject you edited survives, prefixes never compound, and a stale next action is removed rather than stacked. Nothing else moves — no reordering, no invented projects, no driving the UI. Completed threads retire after 14 idle days, and nothing running, blocked, or waiting on you is ever archived.

Seven states, one glance

Every classified, unarchived task carries exactly one of these.

running

a turn is actively working

needs input

waiting on you to answer or approve

blocked

a structured turn error stopped it

next steps

idle, with one concrete thing to do

automation

a healthy scheduled task, idle by design

complete

finished, and eligible to archive

unknown

interrupted or cancelled without a disposition

Give your sidebar a hug.

Either way, ThreadBear explains everything it is about to do, then asks once before it touches a thing.