Talk to us Sign in

Documentation

How Podcode works.

Guides for the pieces you configure: agents and the harnesses that chain them, the memory that carries between sessions, the providers that supply the models, and the integrations and plugins that extend the rest. Most of it is a few keys in one JSON file, or a form in Settings that writes them for you.

Start here Harnesses

~/.config/podcode/config.json

{
  "harness": {
    "review-loop": {
      "description": "Build, then review what was built",
      "chain": [
        "implement",
        { "agent": "test", "on_failure": "implement" },
        "review"
      ],
      "max_hops": 8
    }
  }
}

Getting started

Getting started

The surfaces Podcode runs on, what a workspace and a session are, and where everything is stored.

Install the podcode command, and what each subcommand does.

What the agent may do without asking, how rules are written, and which protections a rule can override.

The config layers, how they merge, and the keys the rest of these docs use.

Agents

What an agent is made of, the four modes, and the ones that ship.

Create an agent

The markdown format, every frontmatter key, and the two defaults that catch everyone.

Delegation vs handoff

task returns backwards, agent_handoff passes forwards. Choosing between them.

Harnesses

A named chain of agents that runs across one session — what it is, and why it exists.

Run the built-in React JS harness end to end, and watch a chain work.

Build a harness

Write your own chain — stages, repair targets, acceptance gates, and stage-owned agents.

Every harness key, the stage-eligible agents, why a run halts, and what chains cost.

Memory

Persistent, workspace-scoped knowledge that carries from one session to the next.

How memories are made

The four extraction points, the gate in front of every write, and git-aware staleness.

Retrieval and the vector store

Two recall arms, why they're fused by rank, and why an off-topic query returns nothing.

Memory map and code graph

Browsing what's stored as a list, a timeline, or a map — and the symbol graph laid out beside it.

Configuration and sharing

Choosing an embedder, where the database lives, and syncing fragments with your team.

Providers

The four kinds of provider, the ones that ship, and how a model's limits are resolved.

Connect a provider

One walkthrough per provider type, from the app and from the terminal.

Deploy a private inference endpoint on rented GPUs, from inside the app.

RunPod cost and lifecycle

The spend cap, idle auto-stop, pause and resume, and terminating cleanly.

Integrations

Connecting Podcode to services that aren't model providers, and how credentials are handled.

Connect a Bluesky account with a revocable app password.

Connect any Mastodon instance with a scoped access token.

Plugins

What a Podcode plugin is, what it can reach, and the boundaries it runs inside.

Write, register, and verify a working plugin in about five minutes.

The module contract — default export, id, server(), and what the runtime hands you.

The four hooks, their payloads, how the pipeline threads values, and what happens when one misbehaves.

Give the agent a new capability with the tool hook — ToolDef, the execution context, permissions, and results.

Registering plugins, per-plugin config, auto-discovery, and the workspace trust boundary.

Four complete plugins — an audit log, a cost guard, output redaction, and a custom tool.

Troubleshooting

The failure modes that produce no error at all, and the log lines that explain the ones that do.

Something missing?

These pages document what ships today, and they grow from what people actually hit. Tell us what you were looking for and couldn't find.