Alto is a workspace for coding agents. Its chat views, pane layouts, commands, and application tools are implemented as TypeScript and React plugins. An agent can modify these plugins from an Alto conversation and apply the changes while the application is running.
Cordis manages plugin dependencies and lifetime. Alto compiles and reloads the affected plugins when a change is applied. If compilation or activation fails, it restores the previous program.
Agents connect through Agent Client Protocol (ACP) or Codex App Server. Each agent runs its own cycle of model requests and tool calls; Alto provides the interface, workspace context, and application tools. Chats can use separate worktrees and run alongside native terminals, browsers, and code review in split panes.
Alto is pre-alpha and under active development. The desktop app currently targets macOS; browser mode supports chat and plugin development. Tagged releases publish a portable macOS app for Apple Silicon on GitHub Releases. See the release process for build and signing details.
Alto is a side project at Block. For agent tools developed by dedicated teams at Block, see Buzz and Berd.
Get started · Agent support · Runtime customization · Development · FAQ
Chat, Terminal, Browser, and Canvas panes can be arranged in resizable splits and grouped into workspace tabs. Conversations can be pinned or reopened from history. Inactive panes remain mounted when you switch tabs, preserving drafts, shells, and browser sessions.
Each chat has a working directory. You can select a project folder or an existing worktree, or ask the agent to create a branch and open a separate chat for it. This lets several chats work in independent checkouts. Backend plugins can also provide remote execution targets.
The chat interface shows tool calls and approval requests. Depending on the provider, it also supports queued messages, steering during an active turn, and subagent progress and transcripts in the Agents panel. The Tasks panel groups work by project and associates chats with individual tasks. The Scheduled panel configures recurring Codex tasks, which run locally while Alto is running or through an external scheduling provider.
You can open source files and diffs, and send inline review comments back to chat. Code Tours pair explanations with the relevant changes. GitHub integration shows pull requests, checks, and review status, and the Editor action opens the current local checkout in Cursor, VS Code, or Zed.
Conversations render Markdown, highlighted code, Mermaid diagrams, and mathematics. Linked source, Markdown, and PDF files open in viewers. Native terminals use libghostty, and embedded browser panes open web pages within the workspace. Plugins can use Canvas pages for custom tools and views.
- Node.js 22.19 or newer and Git.
nix developprovides Node 22 and the command-line build tools if you prefer the pinned development environment. - An agent of your choice, installed and authenticated through its own CLI. Codex CLI is only required for Codex. See agent setup for runtime and adapter configuration.
- macOS and a full Xcode installation for the desktop app's native Ghostty terminal. The Command Line Tools alone are insufficient for that build.
Clone the repository and install its dependencies:
git clone https://github.com/block/alto.git
cd alto
npm ciIf using Nix, enter nix develop after cd alto and before npm ci. Agent CLIs
and Xcode are installed separately. For Codex, run codex login before your
first Codex chat; Alto starts App Server when you use a Codex feature.
Build the native terminal once, then start the development app:
npm run build:ghostty
npm run desktop:devThe native build downloads pinned Ghostty and Zig sources and builds the terminal bridge. You do not need a separate Ghostty application installed. See the native backend notes for build details.
To build and install Alto.app in ~/Applications:
npm run install:mac-app
open ~/Applications/Alto.appFrom a fresh checkout, the Nix path is:
nix develop
npm ci
npm run install:mac-appThe build downloads Electron's app bundle automatically if it is missing. Nix supplies the command-line toolchain; full Xcode must be installed and selected separately for the native terminal build. Network access is required for npm packages, Electron, and the pinned Ghostty and Zig sources.
This development installation links back to your checkout, so keep the checkout in place. Closing the macOS window keeps the workspace running; Cmd–Q quits Alto and stops ordinary terminal processes.
For terminal sessions that survive an Alto restart, install tmux, enable
Terminal Persistence in Plugins, and open new terminals. This extension is
disabled by default. See terminal persistence
for session ownership, shutdown behavior, and limitations.
npm run devOpen the complete URL printed in the terminal. The default origin is
http://127.0.0.1:4317; the startup URL also establishes your local browser
session. ALTO_PORT selects a different port for browser mode.
Browser mode is useful for chat and plugin development. Native Ghostty terminals and embedded web browsing require the desktop app. Alto is a local, single-user application.
Open a chat and select the agent before sending the first message. Selecting
a project sets the chat's working directory. New chats without a selected
project use ~/.alto/scratch, which Alto creates automatically and preserves
between launches, separate from the application's program files. Reopening an
existing conversation keeps its saved working directory.
Use the split controls to place another chat or a supporting pane beside it. Agents can also manage the workspace. For example, you can ask:
Create a branch called docs-cleanup from origin/main and open it in a new chat pane to the right.
A few default macOS shortcuts:
| Shortcut | Action |
|---|---|
| Cmd–K | Search commands, chats, and settings |
| Cmd–D / Cmd–Shift–D | Split beside / below the focused pane |
| Option–Tab | Switch between recent workspace tabs |
| Ctrl–Tab / Ctrl–Shift–Tab | Move to the next / previous workspace tab |
| Cmd–Shift–H | Open chat history |
| Cmd–Shift–A | Toggle the Agents panel |
| Tap Option outside text inputs | Open the leader-key shortcut menu |
The leader key and its action bindings can be changed in Hotkeys. GitHub
features use the gh CLI; run gh auth login before using pull request and
check information.
ACP agents can connect natively or through an adapter. Configure the agent's
command and arguments in program/cordis.json. Each agent uses its own runtime
and authentication; Alto provides a shared chat interface, workspace context,
and application tools.
Codex connects through App Server, which gives Alto access to native history,
approvals, queued messages, steering, and subagent inspection. Alto starts
codex app-server on demand, so Codex CLI is only needed for Codex features.
The agent cannot be changed after a chat's first message. Available models, attachments, steering, and session resumption depend on the provider's capabilities. Code Tour generation and local scheduled tasks currently use Codex.
Permission controls also follow the provider. ACP approval handling does not add Codex's sandbox to another agent. See agent providers for authentication, adapter versions, capability differences, and known limits.
An agent can inspect the running program, discover its tools and UI, and submit
source changes through Alto's reprogramming tools. These changes affect the
application's own plugins under program/. For example, you can ask a local
agent to implement a project-specific view:
Add a Canvas page for this project with a checklist that persists between sessions.
The same mechanism can add a composer action that opens project documentation, change a chat view, or register a keyboard shortcut. Alto compiles and activates the affected plugins in place, restoring the previous program if compilation or activation fails.
A change made from a turn that started with Full access applies immediately. Ask and Auto turns produce a proposal for approval. You can also explicitly ask to review a change before it is applied.
The Plugins panel lists entries and their configuration, with controls to enable or disable them. Each plugin owns its tools, UI, styles, and registrations. Cordis removes these when the plugin unloads. Transport, native integration, and recovery remain in a fixed host so they are available while the program changes.
For source builds, the program lives in your checkout. Saved application state
uses the ignored .codex-cordis/ directory and browser storage. Keep program
changes you want to share under version control.
Additional plugins can live outside the Alto repository. Each directory has an
alto-plugins.json manifest that declares where its entries attach to the
built-in program:
ALTO_PLUGIN_DIRS=/absolute/path/to/my-alto-plugins npm run desktop:devFor launches from Finder or the Dock, configure the same directories in the
ignored local file .codex-cordis/plugin-directories.json, then restart Alto:
{
"version": 1,
"directories": ["/absolute/path/to/my-alto-plugins"]
}On macOS, separate multiple ALTO_PLUGIN_DIRS paths with :. External plugins
are trusted application code. Their source is watched for reloads and is
read-only through Alto's built-in reprogramming tools.
Remote execution becomes available when a plugin registers a backend. The backend supplies authentication, provisioning, and process transport; Alto provides chat, approvals, replay, and reconnect handling. A backend can keep agent processes running while Alto is disconnected. See the remote agent contract and external plugin guide.
The feature code lives in the Cordis program. The smaller fixed host handles processes, transport, plugin loading, native capabilities, and recovery.
| Location | Responsibility |
|---|---|
program/cordis.json |
Plugin hierarchy, defaults, configuration, and enabled features |
program/plugins/ |
Agent integrations, tools, React surfaces, styles, and workspace behavior |
src/server/ |
App Server connection, program runtime, registries, and local web gateway |
src/client/ |
Browser plugin host, transport, shell mounting, and recovery |
src/desktop/ |
Electron application and native capability bridges |
native/ghostty/ |
macOS terminal bridge and native build |
Useful commands, after npm ci:
| Command | Purpose |
|---|---|
npm run dev |
Browser development server |
npm run desktop:dev |
Electron app with development assets |
npm run build |
Client, server, and desktop preload builds |
npm run check |
Design-system audit, typecheck, tests, and production build |
npm test -- tests/todo.test.ts |
Run one test file |
npm run test:paper |
Focused Cordis lifecycle and composition checks |
npm run build:mac-release |
Build a self-contained app in dist/mac/Alto.app |
nix run .#check and nix run .#build-ghostty wrap the corresponding commands
with the pinned toolchain. GitHub Actions runs checks on pushes to main and
on pull requests. Version tags trigger the macOS Apple Silicon release workflow.
A portable release bundles its dependencies and application assets. On first launch, it copies the mutable program into the user's Application Support directory, so live customization can persist there. Release builds are currently ad-hoc signed and are not notarized.
Read the architecture for the runtime boundaries and plugin authoring guide for server and browser APIs, dependency declarations, UI ownership, and cleanup. The Cordis conformance notes describe the lifecycle properties covered by the tests.
See CONTRIBUTING.md for setup, validation, and pull request guidance. Use GitHub issues for bugs, questions, and proposed changes. CODEOWNERS lists the default reviewer; GOVERNANCE.md describes project governance.
Alto is licensed under the Apache License, Version 2.0. See NOTICE for the original license notice retained with the imported source.
The name refers to the Xerox Alto, the computer introduced at Xerox PARC in 1973 that helped pioneer graphical personal computing and hosted early Smalltalk environments.
Alto takes inspiration from the ability to modify a computing environment while using it. Here, that means changing the application's interface and tools through reloadable plugins.
The agent loop is the cycle of requesting model output, executing tool calls, and returning their results to the model. Each connected agent harness runs this loop. Alto communicates with it through ACP or Codex App Server and provides workspace context and application tools. Alto does not implement an agent loop of its own.
Alto's pane splitting and tabbed workspace draw inspiration from Zellij and Herdr. Its panes contain graphical agent conversations, terminals, browsers, and custom plugin views.
| Project | What it provides | Where Alto differs |
|---|---|---|
| DeepSeek Harness | A Cordis-based harness with a replaceable agent loop, model adapters, tools, UI, and live extensions. | Alto uses Cordis for its workspace and connects to existing agent harnesses through ACP or App Server. Those harnesses run the agent loop. |
| Pi | An extensible coding agent with a terminal interface, RPC mode, and a TypeScript SDK. | Alto provides a graphical interface for connected agents, with split chats, native terminals, browsers, worktrees, and code review. |
| Claude Mods | JavaScript or TypeScript hooks inside Claude Code that can change tool behavior and draw or restyle UI in supported Claude interfaces. | Alto plugins implement a separate workspace used across agent providers, including its chat views, panes, shortcuts, and application tools. |
| Codex Plugins | Installable bundles of skills, MCP tools, integrations, and lifecycle hooks, with optional UI on supported surfaces. | Alto's Cordis plugins implement and modify the workspace application itself, including its chat interface and pane layout. |
| Zellij | A terminal workspace with split panes, tabs, reusable layouts, and plugins. | Alto uses a similar pane model for graphical agent conversations, native terminals, browser pages, and React views. |
| Herdr | A terminal workspace for multiple coding agents, with split panes, agent status, and persistent sessions. Each agent runs in its own terminal. | Alto renders structured conversations and approvals through ACP or App Server, alongside browsers, code review, and native terminals. |
Provider capabilities and current integration limits are listed under Agent support.