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. Public Bus sessions actively wake for durable messages while idle, acknowledge only after successful processing, expose peer and task state in the TUI, and support bounded delegation and correlated replies. 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.

Contents

• 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.

Start multiplayer mode with one additional flag:

october --team

On first use, October downloads the pinned Bus release for the current platform, verifies its SHA-256 digest, starts the local daemon, creates a stable per-project scope, and joins every reachable peer in that scope. Scope credentials are stored owner-only in ~/.october/agent/team-scopes.json; execution credentials alone enter the agent process.

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

In separate terminals opened in the same project:

# Terminal 1
october --team --team-id planner --team-name Planner
# Terminal 2
october --team --team-id builder --team-name Builder

The first terminal checksum-installs and starts Bus when needed. Both terminals reuse the project scope and link to reachable peers automatically. The launcher injects execution-scoped credentials; the scope token is not passed to the model-facing process. Idle sessions wake for new messages, persist delivery state in the session, and acknowledge exact message IDs only after a successful settled turn. Failed or aborted turns remain unacknowledged and require /inbox retry.

Use /team for peer presence, /tasks for the shared board, /inbox for delivery state, /delegate for a bounded task request, and /handoff to include a capped excerpt of the current session. A delegation can tighten the receiving turn to read-only or accept-edits; it cannot relax the receiver's local permission policy.

For an existing local or remote Bus, set OCTOBER_BUS_ADDRESS and OCTOBER_BUS_SCOPE_TOKEN before october --team. Use --team-connect-to <peer> for a specific additional link and --team-bus <path> to select a preinstalled runtime.

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

bus      → wakes builder while idle
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. Public Bus receives proven working, idle, user-dialog, and offline states from the harness while registration and process shutdown remain launcher-owned.
• 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.

Bus-delivered delegations may add a temporary read-only or accept-edits ceiling for their processing turn. The strongest restriction wins, it is cleared when the turn settles, and remote context can never broaden the process-owned policy.

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

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.

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, active durable inbox delivery, task UI, bounded delegation, and 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/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.

The scheduled Sync Upstream Pi workflow fetches upstream main, validates a merge with npm run check and ./test.sh, and opens a review branch and pull request. It never merges automatically. The daily October Compatibility workflow builds the requested October Bus revision, runs its MCP adapter conformance profile, exercises active two-harness delivery, and stores the exact Harness and Bus revisions as evidence.

October release tags publish the npm package through trusted publishing, build checksummed native archives, attach GitHub build-provenance attestations, and create a GitHub Release. If OCTOBER_DESKTOP_REPOSITORY and OCTOBER_DESKTOP_TOKEN are configured, the same workflow sends an october-release repository dispatch after publication so Desktop can verify and stage the new version. GitHub provenance does not replace Apple notarization or Windows code signing; those require platform signing identities in the release environment.

Roadmap

• Make the October Harness the clearest reference implementation of the October Bus compatibility contract.
• Publish compatibility evidence for every released Harness and Bus pair.
• 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/. Local team scope tokens are written to team-scopes.json with owner-only permissions. They are used only by the outer launcher and removed before the agent process starts; Bus capabilities, execution tokens, process identity, and readiness evidence remain execution-scoped.

The scope file is access-controlled but not encrypted. Protect the operating-system account and home directory, and rotate or remove a scope in Bus if its token may have been exposed.

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.