October Harness

October's open, multiplayer-first coding harness.

Fast in a terminal. Extensible as a runtime. Native to October Bus.

---

October Harness is a complete open-source coding agent built to work alone and with other agents. Run it as an interactive terminal partner, a one-shot command, a JSON process, an RPC server, or an embedded SDK. Use October inference or bring another supported model provider.

October discovers tools automatically from the public October Bus launcher or October Desktop. Agents can pull durable messages, acknowledge handled work, coordinate tasks, and send correlated replies. Public Bus delivery can wake idle RPC and TUI sessions automatically; print and JSON runs require an explicit prompt to process inbox work. Desktop additionally supplies session and turn context through its hook protocol.

October Bus is the open communication substrate. October is the runtime and control plane above it, adding the visual workspace, automatic staffing, harness selection, quota-aware routing, cross-machine operation, supervision, outcome learning, and Autopilot.

October Harness started as a fork of Pi. Pi remains the foundation for much of the agent core, provider layer, TUI, session model, and extension system. The project has since been substantially changed for October with its own package and CLI, inference and authentication, permission modes, Bus-native tools and hooks, October context handling, managed Desktop runtime, and product identity.

Why another coding harness?

Claude Code, Codex, and Pi already prove that a terminal is a powerful place to work with an agent. October Harness is not an attempt to hide another agent loop or lock developers into a private implementation.

It exists to be the open reference harness for multiplayer-native development:

• useful as a serious standalone coding agent;
• native to agent discovery, durable messaging, delegation, and replies;
• transparent enough for developers to inspect, extend, and self-host;
• concrete enough to show other harness authors what first-class October Bus support looks like;
• deeply integrated with October without exposing October's private cloud or intelligence layer.

Pi optimizes for a small, extensible core. October Harness keeps that foundation and makes a different product choice: multiplayer behavior is part of the first-party runtime, not an afterthought bolted onto a send_message() function.

Compared with other harnesses

October's focus is built-in October Bus support: discovering other agents, exchanging durable messages, and coordinating shared tasks. Other harnesses also support multi-agent work, either built in or through extensions. The difference is how they connect and coordinate.

Harness	Interfaces	Collaboration
October Harness	Terminal, print/JSON, RPC, embedded SDK	Bus peers, durable messages, shared tasks
Pi	Terminal, print/JSON, RPC, embedded SDK	Subagents through extensions, packages, or separate Pi processes
OpenCode	Terminal, desktop, IDE; headless CLI, HTTP server/client SDK	Primary agents and subagents
Cline	IDE extensions, CLI, desktop, embedded SDK	Persistent teams with a task board and mailbox in CLI, SDK, and Kanban; not yet in IDE extensions
Claude Code	Terminal/headless, IDE, desktop, web; Agent SDK	Subagents and cross-session messaging; agent teams are experimental and opt-in
Codex	CLI, IDE, desktop, cloud; SDK and app server	Parallel subagents with separate threads and custom roles

Harness	Customization	Permissions
October Harness	TypeScript extensions, skills, prompts, themes, packages	ask, accept-edits, bypass; default is bypass
Pi	TypeScript extensions, skills, prompts, themes, packages	Project trust and extension-defined tool approvals; no built-in sandbox
OpenCode	Plugins, skills, MCP servers	Per-tool allow, ask, deny rules
Cline	Skills, MCP servers; plugins in CLI, SDK, and Kanban	Tool approvals and configurable auto-approve
Claude Code	Skills, hooks, MCP servers, plugins	Tool rules and approval modes; optional OS-enforced Bash sandbox on supported platforms
Codex	Skills, MCP servers, hooks; plugins in desktop and CLI, not IDE	OS-enforced sandbox with filesystem/network restrictions and separate approval settings

This is not a complete feature list. Documentation checked September 10, 2026; availability varies by version and interface. October's approval controls are not an OS sandbox; see Security.

Contents

• Compared with other harnesses
• Five-minute quickstart
• Update October Harness
• Authentication, models, and providers
• Standalone usage
• Two harnesses, one Bus
• Using it inside October
• Sessions and permissions
• Architecture
• Extensions and customization
• What changed from Pi
• Open-source boundary
• Contributing and upstream sync
• Roadmap
• Security
• License and attribution

Five-minute quickstart

October Harness requires Node.js 22.19 or newer.

npm install -g --ignore-scripts @october-dev/october
october

Run october from your project's directory. If you need to sign in, enter /login inside October and choose October account, Another provider account, or API key. Existing credentials are reused; a separate shell login is not required.

Ask for a quick orientation:

Summarize this repository, explain how to run its checks, and suggest the highest-leverage next task.

October can read, write, and edit files, run shell commands, inspect the repository, and retain the session so you can continue later.

Use /model inside October to choose or change your model.

Update October Harness

From your shell, use the built-in updater for a supported global installation:

october update
october --version

For a global npm installation, you can also install the latest published release directly:

If an older version prints Could not determine latest october version, use this npm command once to replace the updater that depended on the unavailable website feed. The fixed updater reads the published version directly from npm.

npm install -g --ignore-scripts @october-dev/october@latest
october --version

Restart running harness sessions after updating. Your saved credentials, settings, and sessions are preserved. october update updates the harness only; use october update --all to update the harness and installed extensions together.

October Desktop manages its own harness version. Updating the standalone CLI does not change a Desktop-pinned installation.

Authentication, models, and providers

October inference

Start october, enter /login, and choose October account. October opens the browser for approval, then returns you to the terminal session. You can optionally sign in before launching the session with october login from your shell.

Standalone login uses a device-code flow and stores a revocable credential under ~/.october/agent/. Inside October Desktop, the app injects and refreshes the signed-in session, so no separate login is required.

The built-in October provider refreshes its model catalog from the October inference gateway. Before the first refresh, its offline seed catalog contains only october/Qwen/Qwen3.6-35B-A3B-FP8, the recommended default, with text input and reasoning. Paused models such as october/Kimi-K2.7-Code appear only when the gateway lists them.

Existing saved model choices are preserved. If a session still selects Kimi and receives model use not permitted, use /model to select Qwen3.6 or pass --provider october --model october/Qwen/Qwen3.6-35B-A3B-FP8.

October Pro and Max plans also include paid OpenRouter models, listed under openrouter/ (for example openrouter/anthropic/claude-sonnet-5). They are billed at cost from your monthly harness credit. The /model picker shows each paid model's price and marks the others as free. While an October model is selected, the footer shows your remaining credit. Paid models accept text only; images are replaced with a placeholder before the request is sent. On the Free plan, or when your credit runs out, October explains how to upgrade or top up and suggests a free model; it does not ask you to sign in again.

Use /model in the TUI or inspect available models from the shell:

october --list-models
october --provider october

Subscription providers

Run /login to use supported subscriptions for ChatGPT Plus/Pro (Codex), Claude Pro/Max, GitHub Copilot, xAI, OpenRouter, or Radius.

API-key and cloud providers

The inherited multi-provider layer supports Anthropic, OpenAI, Azure OpenAI, Google Gemini and Vertex AI, Amazon Bedrock, DeepSeek, xAI, OpenRouter, Mistral, Groq, Cerebras, NVIDIA NIM, Cloudflare AI Gateway and Workers AI, Vercel AI Gateway, Hugging Face, Fireworks, Together AI, Baseten, Kimi, MiniMax, Qwen, Xiaomi, ZAI, OpenCode, and other compatible endpoints.

Set an environment variable or use /login to store a key in ~/.october/agent/auth.json:

export ANTHROPIC_API_KEY=sk-ant-...
october

Custom model catalogs can connect Ollama, LM Studio, vLLM, and services implementing supported OpenAI, Anthropic, or Google APIs. Custom provider extensions can add new APIs and OAuth flows. See the full provider guide and custom model guide.

Standalone usage

October is a complete local harness even when no October app or Bus is present.

Mode	Command or surface	Best for
Interactive	october	Pairing in the terminal
Print	october -p "Review this diff"	One-shot tasks and scripts
JSON	october --mode json	Structured pipelines and CI
RPC	october --mode rpc	Driving a persistent agent from another process
SDK	Import @october-dev/october	Embedding the agent in another application

Common commands:

october -c                         # continue the latest session
october -r                         # browse previous sessions
october --name "Auth refactor"     # name a new session
october --no-session               # run without persistence
october -p "Summarize this repo"   # one-shot prompt

Bus integration is execution-gated. Public Bus requires the launcher's address, MCP URL, agent ID, execution ID, and agent token. Desktop uses its port, canvas, and node contract. With neither valid configuration, October registers no Bus tools or hooks. Startup never prints “What's New”; use /changelog explicitly to view release history.

Two harnesses, one Bus

For a runnable example without API keys, see Local Bus multiplayer. It starts an isolated pinned Bus and two real SDK worker processes, verifies discovery, task completion, correlated replies, and acknowledgements, then cleans up.

Start a local October Bus, create a scope, and keep its scope token in the launching shell. In separate terminals, using the same scope:

# Terminal 1
OCTOBER_BUS_SCOPE_TOKEN=<scope-token> october-bus agent run --id planner --name Planner -- october
# Terminal 2
OCTOBER_BUS_SCOPE_TOKEN=<scope-token> october-bus agent run --id builder --name Builder --connect-to planner -- october

The launcher injects execution-scoped credentials; October discovers MCP tools without a separate MCP configuration. The scope token is not passed to October. Prompt the planner once; incoming public Bus messages can wake idle RPC and TUI sessions and are acknowledged after successful turn settlement. In Desktop, launch the harness in two terminal nodes on one canvas; Desktop uses its own hook contract.

Ask the first agent:

Find the other agent on this canvas. Delegate a review of the authentication flow,
then wait for its answer and summarize the result for me.

The collaboration is visible in protocol operations:

planner  → list_peers()
bus      → builder [attached, ready, local]

planner  → message_peer(builder, mode=request,
                         "Review the authentication flow for failure cases.")
bus      → request accepted durably as msg_01

builder  → check_inbox()
planner  → add_task(title="Review authentication flow") → task_01
builder  → claim_task(taskId=task_01)
builder  → message_peer(planner, mode=response, responseTo=msg_01,
                         "Found two gaps: expired-device-code recovery and token revocation UX.")

builder  → acknowledge_messages(messageIds=[msg_01])
planner  → check_inbox() → correlated response received

This is more than agent-to-agent chat. The Bus keeps peer identity, reachability, durable delivery, request/reply correlation, shared tasks, dependencies, lifecycle, and human escalation as explicit protocol state. A peer request never expands the receiving harness's permissions.

Using it inside October

October Harness is the first-party terminal agent for the October Desktop app:

• Zero-config authentication. Desktop supplies and refreshes the current October session.
• Managed runtime. Desktop controls its installed harness version. Updating npm alone does not update a Desktop-pinned installation.
• Bus-native collaboration. The harness receives an execution-scoped identity and registers peer, inbox, task, and status tools from the local Bus.
• Lifecycle hooks. Desktop receives session live/offline, pre-prompt, and turn-stop hooks. User-dialog readiness and background inbox wake-up are not implemented. Public Bus registration, heartbeat, and shutdown belong to its launcher.
• October context. Bounded orientation, peer, inbox, and summary context can enter the agent at the appropriate prompt boundary.
• Local authority. Bus credentials and process identity belong to one execution and disappear when that run ends.

The CLI remains the same harness in both environments. October integration adds context and collaboration; it does not replace the open runtime with a private agent implementation.

Sessions and permissions

Sessions

Sessions are append-only JSONL trees stored under ~/.october/agent/sessions/, grouped by working directory. They preserve messages, tool results, model and thinking changes, compactions, labels, extension state, and alternate branches.

Command	Behavior
/resume	Browse saved sessions
/new	Start a fresh session
/name <name>	Give the session a human-readable name
/session	Show the current file, ID, messages, tokens, and cost
/tree	Move through the current session's branch tree
/fork	Start a new session from an earlier user message
/clone	Copy the active branch into a new session
/compact	Summarize older context for a longer working session
/export	Export the session for review

See Sessions, Compaction, and the session format.

Tool permissions

October adds three explicit tool-permission modes:

Mode	Reads	File edits	Shell and other commands
ask	Allow	Ask	Ask
accept-edits	Allow	Allow	Ask
bypass	Allow	Allow	Allow

Set the process policy with --permission-mode, then OCTOBER_PERMISSION_MODE, then global ~/.october/agent/settings.json (in that precedence order). The default is bypass. Trusted project .october/settings.json may only tighten that policy; untrusted project settings are ignored. Policy is fixed for the session, so tool edits cannot grant more authority. Restart with an explicit user-selected mode to change it. Non-interactive operations requiring approval are blocked.

Project trust is separate from tool permissions. It controls whether October loads project-local settings, extensions, skills, prompts, themes, and packages. It is an input-loading boundary, not a sandbox.

Architecture

flowchart TB
    subgraph Entry[Runtime surfaces]
        A[Interactive TUI]
        B[Print / JSON]
        C[RPC]
        D[SDK]
    end

    subgraph Harness[October Harness]
        E[Agent session + message queue]
        F[Agent loop + tools]
        G[Model runtime]
        H[Session manager]
        I[Extension + resource loader]

        subgraph October[Built-in October extension]
            J[Inference + auth]
            K[Permission modes]
            L[Bus MCP client + tools]
            M[Lifecycle + context hooks]
        end
    end

    N[Model providers]
    O[Local files + shell]
    P[(JSONL sessions)]
    Q[October Bus]

    A --> E
    B --> E
    C --> E
    D --> E
    E --> F
    E --> G
    E --> H
    E --> I
    I --> J
    I --> K
    I --> L
    I --> M
    G <--> N
    F <--> O
    H <--> P
    L <--> Q
    M <--> Q

Loading

The public monorepo contains the full path from CLI input to model request, tool execution, session persistence, and Bus collaboration. October's built-in extension uses the same public extension surface available to developers.

Extensions and customization

October is designed to be changed at the edges:

Extension point	What it changes
TypeScript extensions	Tools, commands, providers, events, UI, and lifecycle behavior
Skills	Reusable instructions and domain workflows loaded on demand
Prompt templates	Repeatable prompts exposed as slash commands
Themes	TUI colors and presentation
Packages	Shareable bundles installed from npm or Git

Start with the documentation index, then explore extensions, skills, prompt templates, themes, the RPC protocol, and the SDK.

Included packages

October adds these community Pi packages to your packages setting on first run. Each is pinned to a reviewed version and installs automatically, which adds about a minute to the first start:

Package	What it adds
pi-mcp-adapter	Connect any MCP server (/mcp)
pi-web-access	Web search, page and PDF fetching, and GitHub repo cloning
@juicesharp/rpiv-ask-user-question	Structured questions with typed options instead of guesses
@juicesharp/rpiv-todo	A live todo list that survives reloads and compaction (/todos)
@narumitw/pi-plan-mode	A read-only planning mode (/plan)
pi-lens	LSP, linter, formatter, and type-check feedback while editing

They are ordinary packages: october list shows them, october remove <source> removes one for good, and a version you install yourself takes precedence. October Desktop-managed sessions and offline runs skip this step. These packages are maintained by their authors, not by October.

Also worth a look, installed with october install npm:<name>: pi-subagents for scripted multi-agent workflows, pi-background-tasks for durable background shell tasks, pi-goal-x for tracked /goal planning, and observability integrations such as @langfuse/pi-observability-plugin and @braintrust/pi-extension.

What changed from Pi

October Harness is a real downstream product, not a renamed Pi binary. We continue to inherit and credit substantial upstream work while maintaining October-specific behavior in this repository.

Area	Pi foundation retained	October-specific work
Runtime	Agent loop, tools, provider abstraction, TUI, sessions, RPC, SDK	october CLI/package identity, .october configuration, managed distribution
Models	Multi-provider APIs and catalogs	October inference provider, dynamic October catalog, device login, Desktop session refresh
Collaboration	General extension primitives	Public/desktop Bus MCP tools, pull-based durable inbox and task operations, Desktop session/turn hooks
Context	Project instructions, skills, prompts, extensions	Bus orientation and peer/inbox context, execution identity, turn summaries
Permissions	Project trust and host-process security model	ask, accept-edits, and bypass tool-permission modes
Product integration	Portable terminal harness	October header, Desktop launch contract, safe self-update and first-party runtime behavior

October publishes only @october-dev/october. It does not republish the upstream @earendil-works/pi-coding-agent package. The upstream workspace package names and required notices are preserved.

Open-source boundary

This repository contains the usable harness:

• CLI, interactive TUI, headless modes, RPC runtime, and SDK;
• model and provider support;
• session persistence, branching, compaction, and export;
• project trust and October permission modes;
• October inference and standalone authentication;
• October Bus integration, agent-to-agent tools, lifecycle hooks, and context handling;
• the extension, skill, prompt, theme, and package systems needed to customize it.

It does not contain October backend secrets, private inference credentials, internal admin tooling, proprietary Autopilot or team-staffing logic, quota-routing intelligence, enterprise controls, or October's hosted cloud control plane.

The open harness should be enough to run, study, extend, and use as a reference implementation without needing access to October's private product systems.

Repository layout

Package	Role
@october-dev/october	October CLI, SDK, permissions, inference, and Bus integration
@earendil-works/chord	Application-composition runtime for services, replicated state, RPC, and plugins
@earendil-works/pi-agent-core	Agent loop, tool calling, and state management
@earendil-works/pi-ai	Unified multi-provider model API
@earendil-works/pi-tui	Differentially rendered terminal UI
@earendil-works/pi-protocol	RPC protocol types and transport contract
@earendil-works/pi-client	Client for remote agent sessions
@earendil-works/pi-server	Server runtime for remote sessions
@earendil-works/pi-telemetry	Shared, privacy-aware telemetry primitives

Contributing and upstream sync

October welcomes fixes, documentation, new provider support, extensions, and improvements to its Bus-native behavior. Read CONTRIBUTING.md and AGENTS.md before making changes.

git clone https://github.com/october-dev/october-harness.git
cd october-harness
npm install --ignore-scripts
npm run build:offline
npm run check
./test.sh

Our upstream policy is straightforward:

• keep Pi copyright, MIT license, package attribution, and provenance intact;
• treat Pi as the source of truth for inherited code and track it through explicit, reviewable upstream merges;
• prefer sending generally useful, October-neutral fixes upstream when practical;
• keep October-specific inference, Bus, permission, Desktop, and product behavior in this repository;
• resolve upstream conflicts without weakening October's public harness or Bus contracts;
• document meaningful divergence so contributors can tell which project owns a behavior.

For substantial October-specific work, open an issue before implementation. If a change belongs cleanly in Pi, contributors are encouraged to coordinate it upstream first and then bring it back through the normal sync path.

Roadmap

• Make the October Harness the clearest reference implementation of the October Bus compatibility contract.
• Complete released-harness Bus conformance evidence, then add opt-in idle delivery and user-dialog readiness signals.
• Expand adapter and conformance examples for mixed-harness teams.
• Keep provider and model support current without coupling the harness to one inference backend.
• Improve session portability between standalone, Desktop, RPC, and SDK usage.
• Continue upstreaming generally useful runtime, TUI, provider, and session improvements.
• Grow the extension ecosystem without moving proprietary orchestration into the open harness.

Security

October Harness is a local coding agent. It runs with the operating-system permissions of the user who starts it and does not claim to provide an in-process sandbox.

• Review project trust before loading repository-owned settings, extensions, skills, prompts, themes, or packages.
• Choose an October permission mode appropriate for the task.
• Use a container, VM, micro-VM, or policy-controlled sandbox for untrusted or unattended work.
• Mount only the files and credentials the task needs.
• Treat third-party extensions and skills as executable code and instructions.
• Review changes before committing or deploying them.
• Remember that Bus peers can request work but cannot grant new local authority.

Credentials are stored under ~/.october/agent/; Bus capabilities, tokens, process identity, and readiness evidence are execution-scoped and remain local.

Report vulnerabilities privately through this repository's security policy or GitHub Security Advisories. Do not open a public issue for a security-sensitive report.

License and attribution

October Harness is licensed under the MIT License.

It began as a fork of Pi, and substantial portions of the agent core, AI layer, TUI, sessions, extensions, and supporting packages originate from Pi and its contributors. The required upstream copyright, license, package names, and attribution notices are preserved.

October-specific changes are distributed under the same MIT terms. The license covers the code in this repository; it does not grant rights to October's names, logos, or other brand assets.

---

Built in the open by October, on the open-source Pi foundation.