# WorkerLane

**Harness-agnostic agent coworkers for any agent runtime.** One package that wires team agents, approvals, memory, traces, and handoff contracts into whatever harness you already use.

[![npm](https://img.shields.io/npm/v/@talocode/workerlane)](https://www.npmjs.com/package/@talocode/workerlane)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Part of **[Talocode](https://talocode.site)** — open tools people trust, hosted power behind them.

---

## What it is

AI agents are great at running tasks. The hard part is everything around them: who can run what, what gets approved, what happened last session, and proving it after the fact. WorkerLane bundles those pieces into one package that works with **any agent harness** — no runtime brand loyalty, no side to pick.

- **AI coworkers** — create agents with a name and role, queue tasks, gate destructive work behind approvals
- **Agent-human handoffs** — validate and repair step-to-step payloads against schema contracts so runs never silently drift
- **Full data recording, owned by you** — trace spans with cost and status, plus durable memory that persists across sessions. Everything is stored locally in `~/.workerlane` unless you opt into the hosted path
- **Computer use** — run `screenlane mcp` (`@talocode/screenlane`) alongside `workerlane mcp` to add screen capture, dictate, and command tools to the same harness
- **Works with any harness** — expose the whole bundle as MCP tools and connect any MCP-compatible agent

## Why it exists

The catalog is strong but fragmented — agents, traces, memory, handoffs each ship separately. WorkerLane removes the assembly. One install, one surface, all the pieces wired together. It is positioned as a capability layer above the harness, exactly where compounding value lives.

## Install

```bash
npm install -g @talocode/workerlane
```

or

```bash
pip install workerlane
```

No Office, no runtime, no cloud required. Local engine runs entirely on your machine.

## Quickstart (CLI)

```bash
# start the MCP server — connect any harness to it
workerlane mcp

# create a coworker
workerlane agent create --name "qa-bot" --role "reviews every PR before merge"

# queue a task, gated behind an approval
workerlane agent run --agent <ID> --task "audit the auth flow" --approve

# save and recall memory across sessions
workerlane memory remember --text "deploy is Fridays, freeze after 4pm" --tags ops,deploy
workerlane memory recall --query "deploy"

# start a trace run
workerlane trace start --name "release-check"
```

## Quickstart (MCP — any harness)

```json
{
  "mcp": {
    "workerlane": {
      "type": "local",
      "command": ["workerlane", "mcp"]
    }
  }
}
```

Once connected, these tools are available to any MCP-compatible agent:

| Tool | What it does |
|------|--------------|
| `workerlane_agent_create` | Create a coworker with name + role |
| `workerlane_agent_list` | List coworkers |
| `workerlane_agent_run` | Queue a task; `requireApproval` pauses for a human |
| `workerlane_agent_approve` | Approve/reject a pending run (recorded) |
| `workerlane_agent_complete` | Mark a run complete with its result |
| `workerlane_agent_runs` | List runs, filter by status |
| `workerlane_handoff_validate` | Validate step output against a schema contract |
| `workerlane_handoff_repair` | Validate + lightly repair (drop extras, coerce types) |
| `workerlane_trace_start` | Start a trace run |
| `workerlane_trace_span` / `_span_end` | Record a span (llm/tool/retrieval/handoff) with status + cost |
| `workerlane_trace_complete` | Complete a run → receipt chain |
| `workerlane_trace_list` | List trace runs |
| `workerlane_memory_remember` | Save a memory |
| `workerlane_memory_recall` | Recall relevant memories |
| `workerlane_memory_list` | List saved memories |

**Computer use (sibling server):** install `@talocode/screenlane`, then add a second MCP entry:

```json
{
  "mcp": {
    "screenlane": {
      "type": "local",
      "command": ["screenlane", "mcp"]
    }
  }
}
```

Exposes `screenlane_capture`, `screenlane_dictate`, `screenlane_command`, `screenlane_send`, `screenlane_doctor` to the same harness. Hosted browser automation is available via Agent Browser on Talocode Cloud (`/v1/agent-browser/*`).

## SDK

```ts
import { createAgent, createAgentRun, approveAgentRun, validateHandoff, remember, recall, createTraceRun, startTraceSpan } from '@talocode/workerlane'

const bot = createAgent({ name: 'qa-bot', role: 'reviews every PR before merge' })

const run = createAgentRun({ agentId: bot.id, task: 'audit the auth flow', requireApproval: true })
// → a human approves it before it runs
approveAgentRun(run.id, true)

const r = validateHandoff({
  value: { intent: 'ship', confidence: 0.9 },
  schema: { type: 'object', required: ['intent', 'confidence'], properties: { intent: { type: 'string' }, confidence: { type: 'number' } } },
})

remember('deploy is Fridays, freeze after 4pm', ['ops', 'deploy'])
const facts = recall('deploy')

const trace = createTraceRun('release-check')
const span = startTraceSpan(trace.id, 'verify', 'tool')
```

## Data & ownership

- Everything is local-first. State lives in `~/.workerlane/` (override with `WORKERLANE_DIR`).
- `agents.json` — agent registry + run audit trail with approval decisions
- `memory.json` — durable memory
- `traces.json` — span receipts with cost + status
- Export or delete these files any time — the data is yours.

## Hosted path

For teams that want managed power, WorkerLane is available on Talocode Cloud under `/v1/workerlane/*` with Stacklane billing. The local engine is always free.

| Action | Credits (hosted) |
|--------|------------------|
| `workerlane.agent.run` | 3 |
| `workerlane.agent.approve` | 1 |
| `workerlane.handoff.validate` / `repair` | 2 / 4 |
| `workerlane.trace.start` / `span` / `complete` | 1 / 1 / 2 |
| `workerlane.memory.remember` / `recall` | 4 / 2 |

## Related packages

- `@talocode/worklane` · `pip install worklane-ai`
- `@talocode/memorylane` · `pip install memorylane-ai`
- `@talocode/handofflane`
- `@talocode/tracelane`
- `@talocode/agent-browser` (hosted computer use)

## Talocode ecosystem

| Product | Repo |
|---------|------|
| **WorkerLane** (this package) | [github.com/talocode/workerlane](https://github.com/talocode/workerlane) |
| [Tera](https://github.com/talocode/tera) | Reasoning, writing, coding |
| [WorkLane](https://github.com/talocode/worklane) | Work automation |
| [MemoryLane](https://github.com/talocode/memorylane) | Persistent agent memory |
| [HandoffLane](https://github.com/talocode/handofflane) | Step-to-step schema contracts |
| [TraceLane](https://github.com/talocode/tracelane) | Run tracing + receipts |
| [PolicyLane](https://github.com/talocode/policylane) | Policy gates |
| [GateLane](https://github.com/talocode/gatelane) | Gate enforcement |
| [Agent Browser](https://github.com/talocode/agent-browser) | Browser automation for agents |
| [ScreenLane](https://github.com/talocode/screenlane) | Screen automation |
| [SearchLane](https://github.com/talocode/searchlane) | Search capability |
| [XSearchLane](https://github.com/talocode/xsearchlane) | X search |
| [DocuLane](https://github.com/talocode/doculane) | Office documents for agents |
| [DataLane](https://github.com/talocode/datalane) | Data analysis |
| [ClipLoop](https://github.com/talocode/cliploop) | Video creation |
| [Tradia](https://github.com/talocode/tradia) | Trading |
| [Codra](https://github.com/talocode/codra) | Coding agent |
| [StackLane](https://github.com/talocode/stacklane) | Cloud control plane |

More: [github.com/talocode](https://github.com/talocode) · [talocode.site](https://talocode.site) · [docs.talocode.site](https://docs.talocode.site)

## License

MIT © Talocode