DocsInstall

On this page

A coding agent for your terminal, built on pi

a1 keeps pi’s engine, models, and extensions, and rebuilds the experience around them: persistent prompt history, next-step suggestions, and an interface made for long sessions.

InstallGitHub
a1
Handle empty config files without breaking existing behavior14:02

Checking how the loader reads config files

$ sed -n 1,12p src/config/load.ts

export function loadConfig(source: string) {
  return JSON.parse(source);
}

Took 0.1s

Guarding empty and whitespace-only files, then running the tests

edit src/config/load.ts (+2 −1)

- return JSON.parse(source);
+ const text = source.trim();
+ return text ? JSON.parse(text) : {};

Took 0.2s

$ npm test (timeout 120s)

Tests     8 passed (8)
Duration  1.8s

Took 1.8s

Empty files now return an empty config. Existing behavior is preserved and covered by tests. Nothing has been committed.

Also warn when a config file is empty, so it doesn’t fail silently14:05

Looking for the project’s existing warning helper

$ rg -n "export function warn" src

src/log.ts:8:export function warn(message: string) {

Took 0.1s

Warning on the empty branch and adding a test for it

edit src/config/load.ts (+6 −1)

+ import { warn } from '../log';
- return text ? JSON.parse(text) : {};
+ if (!text) {
+   warn('Config file is empty; using defaults');
+   return {};
+ }
+ return JSON.parse(text);

Took 0.2s

edit test/config/load.test.ts (+4)

+ it('warns on an empty file', () => {
+   loadConfig('  ');
+   expect(warn).toHaveBeenCalledOnce();
+ });

Took 0.2s

$ npm test (timeout 120s)

Tests     9 passed (9)
Duration  1.9s

Took 1.9s

Empty config files now log a warning and fall back to defaults. A new test covers it, and all 9 tests pass. Nothing has been committed.

Add a --config flag so I can load a different file14:09

Checking how the CLI parses its arguments

$ sed -n 1,9p src/cli.ts

import { readFileSync } from 'node:fs';
import { parseArgs } from 'node:util';
import { loadConfig } from './config/load';

const { values } = parseArgs({
  options: { verbose: { type: 'boolean' } },
});
const source = readFileSync('orbit.json', 'utf8');

Took 0.1s

Adding the flag, with orbit.json as its default

edit src/cli.ts (+2 −2)

-   options: { verbose: { type: 'boolean' } },
+   options: { verbose: { type: 'boolean' }, config: { type: 'string', default: 'orbit.json' } },
- const source = readFileSync('orbit.json', 'utf8');
+ const source = readFileSync(values.config, 'utf8');

Took 0.2s

Trying the flag against an empty fixture

$ npx tsx src/cli.ts --config fixtures/empty.json

warn: Config file is empty; using defaults
orbit ready (0 services)

Took 0.6s

$ npm test (timeout 120s)

Tests     9 passed (9)
Duration  1.9s

Took 1.9s

orbit now accepts --config <path> and still defaults to orbit.json. It works with the empty fixture, and all 9 tests pass. Nothing has been committed.

Document the flag in the README, then commit everything14:12

Finding the usage section in the README

$ rg -n "## Usage" README.md

42:## Usage

Took 0.1s

Adding an options list under Usage

edit README.md (+4)

+ ### Options
+
+ - `--config <path>`: config file to load (default `orbit.json`)
+ - `--verbose`: print detailed logs

Took 0.2s

Reviewing the changes before committing

$ git status --short

 M README.md
 M src/cli.ts
 M src/config/load.ts
 M test/config/load.test.ts

Took 0.1s

$ git commit -am "Warn on empty config and add --config flag"

[main 3f9c2ab] Warn on empty config and add --config flag
 4 files changed, 18 insertions(+), 4 deletions(-)

Took 0.2s

Committed as 3f9c2ab on main. The README now documents --config and --verbose. Nothing has been pushed.

This is an illustrative session. The look and experience of the terminal are subject to change. Install a1 to see the current release.

Vision

A better experience, not a bigger core

a1 keeps the essence of pi: a small, focused core. Everything else is built on top, from the details that make a working day smoother to the features that will matter as agentic engineering grows.

Persistent prompt history

Recall what you typed across sessions and projects, not just the current one. Stored locally. Can be turned off in Settings.

Next-step suggestions

After a response, a1 can propose a next prompt. Accepting only places it in the editor. Nothing is sent until you press Enter.

An interface that keeps its place

Prompts, tool output, and responses are laid out to be read. Scroll back through a long answer, then return to the editor without losing context.

  • Resume a session

    Leave a1 and come back with a1 --session <id> from the same project.

  • Paste images

    Drop a screenshot into the prompt. Size limits are configurable in Settings.

  • Select and copy

    Select transcript text with the mouse and copy it, even while a response is streaming.

  • Manage extensions

    a1 install, remove, list, and update for npm, Git, or local packages.

  • Update notices

    a1 checks for a newer release at most once a day and shows the command. It never installs anything by itself.

  • Isolated profile

    Everything lives in ~/.a1/agent. Your pi profile is never read, copied, or changed.

Architecture

Built on pi, wrapped in the a1 experience

A better interface shouldn’t cost you the tools you already have.

pi handles models, sessions, and tool execution. a1 owns the layer you interact with and stays compatible with pi extensions. Install the packages you already use and keep working the way you like.

Extensions
Install pi-compatible packages from npm, Git, or a local path. Connect MCP servers through an adapter.
Isolation
a1 keeps its own profile at ~/.a1/agent. Your pi settings and sessions are not imported or changed.
License
MIT-licensed, inspectable source. No a1-only model requirement. Provider terms and usage costs still apply.
a1

Experience layer

interface · prompt history · suggestions · profile

pi

Coding engine

models · sessions · tool execution

  • extensions
  • skills
  • prompt templates
  • themes
  • MCP adapter
  • model provider
Models, tools, and sessions come from pi. The interface, history, and suggestions come from a1.

Comparison

Everything from pi, nothing to give up

a1 is pi with a different front. Your models, extensions, and workflow carry over. What changes is the layer you spend all day looking at.

pi and a1: shared foundation and the a1 experience
Capabilitypithe extensible foundationa1pi, with the a1 experience
Coding tools✓Read, edit, run commands✓Powered by the pi engine
Model choice✓Multiple providers✓Same providers, through pi
Extensions & workflows✓Extensions, skills, templates, themes✓pi-compatible ecosystem
License✓MIT✓MIT
Terminal interfacepi’s interface✓Redesigned interface
Profile & settings~/.pi/agent~/.a1/agent

This compares the pi foundation a1 uses with a1’s documented behavior, not every community extension or future pi release. pi is intentionally extensible, and custom packages can add overlapping capabilities. Features may vary by release.

keep

Everything pi gives you stays

The same engine, the same providers, the same extension packages. a1 runs pi underneath and does not fork its tool behavior.

gain

A better experience on top

Persistent prompt history, next-step suggestions, a redesigned transcript, mouse selection and copy, and a profile that is yours.

no risk

Your pi setup stays untouched

a1 uses its own profile and never touches ~/.pi/agent. Try it on one project. Remove it with nothing to clean up.

Roadmap

One version, one target

Each version is a milestone a1 is working toward, in order. Versions describe targets, not dates or features available today.

  1. 0.1.X

    Infrastructure

    Repository, packaging, installer, and release pipeline in place.

  2. 0.2.X

    Pi paritycurrent

    Everything you rely on in pi works in a1, with an improved UX around it.

  3. 0.3.X

    Multi-agent

    Run several agents side by side from one a1 session.

  4. 0.4.X

    Orchestrator

    Split a task across agents and coordinate their results.

  5. 0.5.X

    Multiplexer

    Watch and steer many agent sessions in one terminal.

  6. 0.6.X

    Custom design

    A fully a1-designed interface across every view.

  7. 0.7.X

    Extensions

    Extensions built for a1, alongside the pi ecosystem.

  8. 0.8.X

    Remote agents

    Hand work to agents running on other machines.

  9. 0.9.X

    Mobile app

    Check on remote agents and approve their work from your phone.

  10. 1.0.X

    Public release

    Stable, documented, and ready for everyday use.

The roadmap may change without notice. Follow the repository for progress and releases.

Installation

Up and running in a minute

Install a1, open a project, and start with a small task. Bring your pi extensions and the model provider you already use.

  1. 1
    Install

    One command. Requires Node.js ≥22.19 and <25 with npm.

  2. 2
    Open a project

    Run a1 in any project directory. Your editor stays the same.

  3. 3
    Connect a model

    Use /login for provider access and /models to choose a model. Usage is billed by your provider.

terminalnpm
npm x -y -- @timurproko/a1-install

cd your-project && a1

# then /login and /models inside a1

release
latest
develop
next

FAQ

Questions, answered plainly

What exactly is a1?

a1, Agent Number One, is an open-source, terminal-native AI coding agent built on pi. It adds an a1-owned interface, persistent prompt history, and optional next-step suggestions around pi’s coding engine. A multi-agent workspace is the longer-term direction, not a currently available capability.

How is a1 different from pi?

pi supplies the underlying coding engine and extension ecosystem. a1 focuses on the experience around that engine: how you interact with a session, recall prompts, read output, and decide what to do next. It is a separate project built on pi, not a replacement for its ecosystem.

Will my pi extensions work?

a1 preserves pi extension compatibility. Install packages from npm, Git, or a local path into a1’s own profile. Your existing pi profile is not automatically imported. For MCP tools, install an adapter such as pi-mcp-adapter, then run /mcp setup inside a1. See the extension instructions.

Do I need to change my editor?

No. a1 runs in your terminal, alongside the editor and development tools you already use. Open a terminal in your project directory and launch a1. It works with your project files; you do not need to move your code into a new hosted workspace.

How do I install a1 and get started?

Install Node.js ≥22.19 and <25 with npm available, then run:

npm x -y -- @timurproko/a1-install

Open your project directory and run a1. Use /login to configure provider access and /models to choose an available model. Start with a small task, such as explaining a module or reviewing a change. See the installation guide.

Which models can I use?

a1 connects to models through the pi engine. Available choices depend on the providers supported by your installed release and the credentials or subscriptions you configure. a1 does not require an a1-exclusive model. Use the model selector to see your available options; provider terms and limits still apply.

Is a1 free to use?

a1’s source code is available under the MIT license. Model access is separate: you bring a supported provider account, subscription, or API credentials, and that provider’s pricing and terms apply. Optional prompt suggestions make additional model requests. Open-source software does not mean unlimited or free model usage.

Is the multi-agent workspace available?

Not yet. Multi-agent work is a roadmap target for version 0.3.X, not a released feature. Today, a1 focuses on the pi-powered coding experience. Follow the repository for development updates.

Will a1 change my existing pi setup?

a1 keeps its profile at ~/.a1/agent, separate from pi’s ordinary ~/.pi/agent profile. It does not automatically copy, merge, or import your pi settings, credentials, extensions, or sessions. Configure a1’s provider access and install your preferred extensions independently. Both tools can still edit the project files you give them access to.

Can I connect MCP servers and my own tools?

Yes, through compatible extensions. For example, install the MCP adapter with:

a1 install npm:pi-mcp-adapter

Then launch a1 and run /mcp setup. MCP connectivity comes from the adapter, not a separate built-in a1 MCP service. Only install extensions and connect servers you trust; they can execute code or access data using the permissions you provide.

Do suggestions run actions automatically?

No. A next-step suggestion is proposed text, not approval or a submitted prompt. Pressing Tab accepts it into the editor; you still press Enter separately to send it. You can edit or ignore it, and turn suggestions off in Settings. Once you submit a task, the coding agent can use its enabled tools. Suggestion controls are not a sandbox or an approval gate for every tool call.

Where does my data go?

a1 uses ~/.a1/agent for its profile. Persistent prompt history is stored locally as unencrypted text in a separate database and can be disabled in Settings; disabling it does not delete saved entries. Model requests go to your configured provider. Terminal-native does not mean local inference. Read the history and storage documentation for details.

Does a1 run entirely on my machine?

The terminal application and its file tools run on your machine. Model inference happens wherever your configured provider runs it. With a remote provider, requests containing task context are sent to that provider. A local-model setup depends on a compatible endpoint and configuration; a1 is not an offline model bundled with the installer.

Can I return to an earlier session?

For a persisted a1 session, use the resume command printed when you leave it, or run a1 --session <id> from the original project directory. Persistent prompt history is different: it recalls what you typed, not the full conversation or an agent’s memory. See the session documentation for current behavior and storage options.

How do I update a1?

Run a1 update to install the release channel. Run a1 update --extensions to update installed packages, or a1 update --models to refresh model catalogs. Development previews are available with a1 update --develop; these can differ from a stable release. Check the repository for release instructions and changes.

What should I know before letting an agent change code?

Treat generated code and commands as work to review, not guaranteed-correct output. Use version control, inspect diffs, run tests, and keep secrets out of prompts. The agent’s tools can read, change, and execute files with the permissions of the process. For untrusted code or unattended work, use an appropriate container or sandbox. A polished interface is not a security boundary.

Where can I follow progress or report a problem?

a1 is developed in the open on GitHub. You can inspect the source, follow releases, and report reproducible issues. Include your a1 version, operating system, terminal, and a minimal example. Remove private prompts, credentials, and project data before sharing logs or screenshots.