Skip to content

The-CowKing/task-talk

Repository files navigation

Task Talk

Here's a free MCP that fixes the spawn-and-forget failure mode in Claude. We use it internally as part of a larger system — separating it out so the community gets the primitive.

Task Talk gives your Claude PM-to-children direct communication. No more fire-and-forget; the PM can message, check, redirect, and verify in real time.

Task Talk is a small, standalone MCP server plus a companion skill. Together they let a PM (the parent Claude session driving the work) spawn child processes, stay in the loop with them — checking, messaging, redirecting — and verify what they actually did before reporting "done" to the user.

It exists because the default behavior is broken. The current pattern looks like this:

user:  "add a regression test and run the suite"
PM:    spawns a child
child: "I have completed the task ✅"
PM:    "done!" → user
user:  runs the suite → test doesn't exist → trust lost

Task Talk replaces it with this:

user:  "add a regression test and run the suite"
PM:    spawn_helper(prompt=..., role="coder") → helper_id
child: "I have completed the task ✅"
PM:    check_helper(helper_id)
       → claimed_done_but_unverified: TRUE  ← the key signal
PM:    reads the file, runs the test
PM:    verify_helper(helper_id, note="test file present, pytest green")
PM:    "done — added tests/test_issue_482.py, suite passes" → user

Same delegation pattern. PM ↔ children stays open the whole time, and verification is baked in.

Naming: in the docs we talk about PM ↔ children. In the code, the spawned process is called a helper — that's the technical noun (spawn_helper, helper_id, helper_log). PM and child are the roles; helper is the thing on disk.


Install

Task Talk is pure Python (≥ 3.10) and depends only on the mcp SDK.

pip install git+https://github.com/The-CowKing/task-talk.git

or clone locally and pip install -e . from the repo root.

Claude Desktop

Add this to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "task-talk": {
      "command": "task-talk"
    }
  }
}

If task-talk isn't on your shell's PATH, use the explicit Python form:

{
  "mcpServers": {
    "task-talk": {
      "command": "python",
      "args": ["-m", "task_talk.server"]
    }
  }
}

Claude Code

claude mcp add task-talk -- task-talk

or for the Python module form:

claude mcp add task-talk -- python -m task_talk.server

Configuration

Env var Default What it does
TASK_TALK_AGENT_CMD claude --print Default CLI invoked by spawn_helper(prompt=...) when no explicit command is given — i.e. the binary that runs as the child.
TASK_TALK_STATE_DIR ~/.task-talk-state Where helper logs and the registry live.

Companion skill (recommended)

Drop skills/task-talk-orchestration/SKILL.md into your agent's skills directory. It teaches the PM the PM-to-children verification protocol so the MCP tools get used the way they're meant to be. The skill + the MCP are the two halves of the same thing: the MCP gives the PM the channel to its children; the skill teaches the PM what to do with it.


Architecture

        ┌──────────────────────────────────┐
        │           PM (Claude)            │
        │  - decides what to delegate      │
        │  - messages / redirects children │
        │  - VERIFIES child output         │
        │  - reports to user with evidence │
        └────────────────┬─────────────────┘
                         │
                    MCP (stdio)
                         │
        ┌────────────────▼─────────────────┐
        │       Task Talk MCP server       │
        │  - spawn_helper   - helper_log   │
        │  - check_helper   - verify_helper│
        │  - list_helpers   - kill_helper  │
        │  - send_to_helper - reset_helpers│
        │                                  │
        │  Surfaces:                       │
        │   claimed_done_but_unverified ⚠ │
        └───┬──────────┬─────────────┬─────┘
            │          │             │
            ▼          ▼             ▼
        ┌────────┐ ┌────────┐   ┌────────┐
        │child 1 │ │child 2 │ … │child N │
        │(helper)│ │(helper)│   │(helper)│
        └────────┘ └────────┘   └────────┘

Each child is a subprocess.Popen — a "helper" in the code. The MCP keeps a registry on disk (~/.task-talk-state/helpers.json), captures stdout/stderr to per-child log files, and scans those logs for completion claims so the PM can see "this child says it's done but you haven't verified it yet."

State is JSON. Logs are plain text. The PM (or you) can inspect everything by hand whenever you want.


The tools

Tool What the PM uses it for
spawn_helper(prompt, role?, command?, cwd?) Launch a child. Returns helper_id.
check_helper(helper_id, tail?) Status snapshot with claimed_done_but_unverified flag.
list_helpers(include_verified?) All children at a glance.
helper_log(helper_id, tail?, stream?) Read a child's full or tailed log.
send_to_helper(helper_id, message) Message a running child (PM → child direct comms).
kill_helper(helper_id, force?) Terminate a runaway child.
verify_helper(helper_id, note) Mark verified — requires a real note about what the PM checked.
reset_helpers(only_finished?) Clear the registry. Won't kill live children.

The full docstrings on each tool double as PM-facing instructions — read them with mcp inspector or look at task_talk/server.py.


Example

See examples/iterative_qa_loop.py for a runnable demo: PM spawns a fake child, watches it claim completion, sees the verification flag raised, then either refuses to verify (when the child lied) or marks it verified (when the work is actually there).


What's NOT in this repo

Task Talk is the dispatch primitive — the PM-to-children channel in isolation. We use it inside a larger system that includes a persistent memory substrate, consolidation passes, integrated-information metrics, and a federation layer for multi-agent coordination. None of that is in this repo. What you're getting is the clean, single-purpose, dependency-light piece: PM spawns child, PM stays in the loop, PM verifies before reporting.

If Task Talk solves a real problem for you, the same approach scales much further. Build on it. Or wait — there'll be more.


License

MIT — see LICENSE.


Contributing

Issues and PRs welcome. Keep it small. The whole point of Task Talk is to be a primitive — if a feature would turn it into a framework, file an issue first.

About

Spawn-with-follow-through MCP for Claude. Fixes the fire-and-forget failure mode. Extracted from a larger system.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages