Guidebook

Say the work plainly.
Threadron picks the right state shape.

Use these phrases when you want an agent to capture context, create work, update a thread, remember a decision, or prepare a clean handoff.

Phrase map Decision boundary
Mental model

Task means do this. Context means remember this. Thread means resume here.

You do not need to name MCP tools in normal use. Say what you mean. A connected agent should translate your intent into the right Threadron call, then report back only after the write succeeds.

If an agent says it recorded something, it should have actually called a threadron_* tool and received a successful result. If tools are missing, the correct answer is setup help, not fake certainty.

Universal capture

When you are dumping raw thoughts

These phrases put unstructured input somewhere safe before it becomes work or context.

"Remember this for later: the deploy kept failing because Railway had stale env vars."
Tool
threadron_capture_inbox
Result
Creates an inbox item for later parsing or promotion.
Why
The thought may matter, but it is not yet a clean task or durable object.
"Drop this into Threadron: open question whether OpenClaw reloads MCP config without a gateway restart."
Tool
threadron_capture_inbox or threadron_create_context
Result
Captures the raw question, or stores a question context object if the agent has enough structure.
Why
Questions are context until someone is explicitly assigned to answer them.
"This is not a task, just keep it in the project memory."
Tool
threadron_create_context
Result
Creates a memory or note object scoped to the domain or thread.
Why
Prevents the task board from becoming a junk drawer.
Threads

When you want resumable work

Threads are durable streams: current state, next action, blockers, artifacts, and member tasks.

"Start a thread for wiring Hermes and OpenClaw into shared state."
Tool
threadron_create_thread
Result
Creates a durable thread with a resume snapshot.
Why
The work may span agents, devices, or sessions.
"Update the thread: transport works, but live agent behavior is still flaky."
Tool
threadron_update_thread
Result
Updates current state and next action for anyone arriving cold.
Why
Thread snapshots are the fastest way to resume without rereading everything.
"Give me the handoff prompt for this thread."
Tool
threadron_resume or threadron_get_thread
Result
Produces a pasteable prompt with current state, next action, blockers, and focus task.
Why
Useful when moving work to another agent or another machine.
Tasks

When you want actionable work

A task should have a clear outcome and a next action. If it is only a fact, decision, or resource, use context instead.

"Create a task for OpenClaw to verify live prompt evals and report failures."
Tool
threadron_create_task
Result
Creates a work item with goal, outcome, owner, current state, and next action.
Why
There is a clear action and someone can complete it.
"Before you work on that, claim it."
Tool
threadron_claim
Result
Places a time-bounded claim on the task.
Why
Prevents duplicate work when multiple agents are active.
"Mark it blocked: need Railway logs from the latest failed deploy."
Tool
threadron_add_context then threadron_update_state
Result
Adds the blocker to the timeline and structured task state.
Why
The next agent sees both the blocker and the reason it happened.
Context objects

When it should be remembered, not done

Shared context objects are the natural home for notes, decisions, resources, people, incidents, routines, questions, and memories.

"Decision: OpenClaw should use mcp-remote for Threadron, not direct URL MCP."
Tool
threadron_create_context with type decision
Result
Stores a durable decision with rationale.
Why
A future agent should follow this choice without rediscovering it.
"Resource: production dashboard is threadron.com/dashboard; deploys go through Railway."
Tool
threadron_create_context with type resource
Result
Stores a link or operational pointer outside the task queue.
Why
Resources are lookup context, not work.
"Question: do Hermes and OpenClaw actually call the context tools in live mode?"
Tool
threadron_create_context with type question
Result
Stores the unknown for later research or human answer.
Why
A question only becomes a task when someone is assigned to answer it.
Artifacts and outcomes

When something was produced

Artifacts make outputs visible: branches, PRs, commits, files, docs, plans, patches, or terminal output.

"Attach the PR and commit to the task."
Tool
threadron_create_artifact
Result
Adds the branch, PR, commit, file, or plan to the task's artifacts.
Why
Outputs should be inspectable without scrolling through chat.
"Record what changed and mark the task complete."
Tool
threadron_add_context, threadron_update_state, then threadron_release
Result
Creates an outcome trail, closes the work, and frees the claim.
Why
The dashboard can show recent outcomes instead of stale cards.
Session start

When an agent arrives cold

The first move should orient the agent without making it re-investigate everything.

"Check Threadron first, then tell me what needs attention."
Tool
threadron_checkin
Result
Returns active threads, in-progress work, pending work, blockers, and inbox items.
Why
This is the agent equivalent of opening the dashboard's attention view.
"What changed since last time on the Threadron UI work?"
Tool
threadron_list_threads, threadron_get_thread, and possibly threadron_list_context
Result
Summarizes changed tasks, context, artifacts, blockers, and next actions.
Why
Humans want deltas, not a raw dump of every record.
Sprints

When you want a time-boxed focus set

Sprints are a planning overlay across tasks and threads. Use them for weekly focus, review, rollover, and capacity conversations.

"Start a sprint for this week around Threadron onboarding."
Tool
threadron_create_sprint
Result
Creates an active planning window with goal, dates, and optional domain scope.
Why
The sprint names what humans are trying to finish now.
"Add this thread to the current sprint as committed work."
Tool
threadron_add_sprint_item
Result
Links exactly one task or one standalone thread to the sprint as planned, committed, or stretch.
Why
Sprints group existing execution state; they do not replace it.
"What slipped from this sprint?"
Tool
threadron_get_sprint
Result
Shows committed, stretch, blocked, completed, and still-open focus items.
Why
Review and rollover need the sprint overlay plus live task/thread status.
Decision boundary

Which shape should the agent choose?

If the user means... Use What happens
"Do this" threadron_create_task A work item is created with goal, owner, status, next action, and outcome.
"Keep this stream resumable" threadron_create_thread or threadron_update_thread A durable resume snapshot is available for any future agent or human.
"Remember this" threadron_create_context A note, decision, resource, question, or memory is stored outside the task board.
"I am not sure what this is yet" threadron_capture_inbox The raw thought lands in the inbox for later parsing, promotion, or remembering.
"I made progress" threadron_add_context plus threadron_update_state The timeline explains why, and structured state says what changed.
"Here is the output" threadron_create_artifact The branch, PR, commit, file, plan, doc, or terminal output becomes inspectable.
"Plan this week" threadron_create_sprint or threadron_add_sprint_item A sprint groups existing tasks and threads into a time-boxed focus set.
"I am starting work" threadron_claim The item is locked for that agent until release or expiry.
"I am pausing" threadron_add_context, threadron_update_state, threadron_release The next agent gets a clean handoff and the claim is freed.
Implicit retrieval

When agents should check context first

Threadron should feel more like scoped retrieval than a manual filing cabinet. Agents should fetch the smallest relevant slice before answering when remembered context could change the result.

"Plan this around my usual schedule."
Tool
threadron_list_context
Result
Searches Personal memories, routines, and preferences before suggesting a plan.
Why
The user should not need to repeat stable constraints every session.
"Draft a reply to Sarah."
Tool
threadron_list_context with type person
Result
Looks for relationship context and communication preferences for Sarah.
Why
People context should be applied narrowly, not dumped wholesale.
"Continue the onboarding work."
Tool
threadron_checkin, then threadron_get_thread or threadron_get_task
Result
Reads the active state, blocker, next action, and recent timeline before acting.
Why
Resume requests need shared state first, not reconstructed memory.
Copy block

Prompt snippet for agents

Paste this into an agent instruction file when you want it to infer the right Threadron call from ordinary language.

agent instruction When the user asks to do work, create or update a Threadron task. When the user asks to keep a stream resumable, create or update a Threadron thread. When the user says to remember a fact, decision, link, question, routine, person, incident, or preference, create a Threadron context object. When the user dumps an ambiguous thought, capture it in the Threadron inbox. Before answering requests involving preferences, people, routines, reminders, scheduling, prior decisions, resources, or resume/handoff, call threadron_list_context with a narrow relevant filter. When the user plans this week, current sprint, committed work, stretch work, slipped work, or rollover, use Threadron sprint tools as an optional planning overlay. When adding a sprint item, pass exactly one of task_id or thread_id. Prefer task_id for normal work items; use thread_id only for standalone thread focus. When you make progress, pair timeline context with structured state updates. When you produce an output, attach it as an artifact. Never claim Threadron was updated unless the relevant threadron_* tool call succeeded.