Overview

a1 is an open-source coding agent for the terminal. It runs the pi coding engine underneath and puts its own interface around it: a fullscreen transcript, paste chips, persistent prompt history, and optional next-step suggestions.

How a1 relates to pi

a1 pins a tested release of pi and uses it for everything the agent does: reading and editing files, running commands, talking to model providers, sessions, extensions, and skills. What a1 adds is the layer you look at all day. If you already use pi, your knowledge carries over; most of the Basics pages describe pi behavior as it appears inside a1.

a1 keeps its own profile in ~/.a1/agent. It never reads or changes your pi profile in ~/.pi/agent.

Where to start

Find what you need

Installation

a1 installs from npm with a small installer that sets up the a1 command and checks that your shell finds it.

Requirements

• Node.js 22.19 or newer, below 25, with npm.
• A terminal. a1 is tested on Windows, macOS, and Linux.
• An account or API key for a model provider. Usage is billed by that provider.

Install

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

The installer installs @timurproko/a1 globally, activates it, and verifies that a1 on your PATH points at the new install. When everything checks out it prints a1 successfully installed. Running it again when a1 is already installed performs an update instead.

Development previews

Preview builds come from the develop channel. They get new features first and can differ from the stable release.

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

Add a preview number or exact version to pin one, for example --develop 0.2.4-dev.663.

If installation fails

Add --verbose to the installer command to print more detail about a failure.

Quickstart

From a fresh install to a reviewed change in a few minutes.

1. Open a project

$ cd your-project
$ a1

The first launch creates the profile in ~/.a1/agent. Nothing is copied from pi. In a new project, pi asks whether to trust it; you can change that decision later with /trust.

2. Connect a model

Run /login to authenticate with a provider, then /models to choose a model. Provider credentials from environment variables also work.

3. Send a small task

Describe what you want and press Enter. Reference files with @ to search and add them to the prompt. Start with something you can verify quickly, such as explaining a module or adding a test.

Explain how @src/auth/session.ts refreshes tokens, then add a test for the expiry path.

4. Review the result

The agent edits files and runs commands with your permissions. Inspect the diff and run your tests before you commit. Press Esc to stop a response that is going the wrong way.

5. Leave and come back

Quit with /quit, Ctrl+D on an empty editor, or Ctrl+C twice. a1 prints a resume command; run it from the same directory to continue. See Sessions.

Models & thinking

a1 works with the providers pi supports. You choose the model and how much it thinks.

Providers

/login configures provider authentication and /logout removes it. Credentials are stored in ~/.a1/agent/auth.json, separate from pi.

Choosing a model

/models opens the model dialog. It switches the active model and manages the scoped list you cycle through.

Outside the dialog, Ctrl+P cycles forward through the scoped models. Cycle backward with Alt+P on Windows and WSL, or Shift+Ctrl+P elsewhere.

Thinking level

/thinking opens a selector. Levels range from off through minimal, low, medium, high, xhigh, and max, depending on what the model supports. Ctrl+L cycles levels without opening the selector, and Ctrl+T shows or hides thinking blocks in the transcript.

The current model and thinking level are always visible in the footer.

Sessions

Every conversation is saved as a session you can resume, branch, export, or share.

Resume a session

When you quit, a1 prints the command to come back. Run it from the original project directory.

$ a1 --session <id>

--session also accepts a path to a session .jsonl file. If the sessions live somewhere other than the default, add --session-dir <dir>. Inside a1, /resume opens a picker.

An ID is looked up in the current project first. If it belongs to another project, a1 asks before creating a fork here. A missing session is an error, never a silent empty start.

Session commands

Pressing Esc twice on an empty editor opens the tree or a fork, depending on the Double-escape action setting.

Where sessions live

Sessions are stored under ~/.a1/agent/sessions/. The PI_CODING_AGENT_SESSION_DIR environment variable or --session-dir changes the location.

Slash commands

Type / in the editor to open the command menu above the prompt. It filters as you type and shows a count of matches.

Built-in commands

Session commands such as /new, /resume, /tree, and /export are listed on the Sessions page. Extensions, prompt templates, and skills add their own commands to the same menu.

Referencing files

Type @ to search the project and add a file to your prompt. Tab completes paths.

Running shell commands

Keyboard shortcuts

The defaults below are what a1 ships with. Run /hotkeys to see the effective list, including your own bindings.

Prompt

Transcript

Models and flow

Custom bindings

Override any binding in ~/.a1/agent/keybindings.json, then run /reload.

Extensions & packages

a1 runs pi packages: extensions, skills, prompt templates, and tools. Install them into the a1 profile from npm, git, or a local folder.

Install, list, remove

$ a1 install npm:pi-mcp-adapter
$ a1 list
$ a1 remove npm:pi-mcp-adapter

Sources can be npm:@scope/name, git:github.com/user/repo, an https:// or ssh:// repository URL, or a local path like ./my-extension. a1 uninstall is an alias for a1 remove.

Update packages

$ a1 update --extensions   # all packages
$ a1 update npm:pi-mcp-adapter   # one package

MCP servers

MCP support comes from an extension rather than a built-in service. Install the adapter, launch a1, and run /mcp setup.

Profile scope

These commands manage the a1 profile only. Packages installed in pi are not visible to a1, and the other way round. Install the extensions you want in each.

Skills & templates

Skills and prompt templates are reusable instructions you invoke from the command menu.

Skills

a1 loads skills from ~/.a1/agent/skills/, the project's .pi/skills/, and ~/.agents/skills/ or .agents/skills/.

By default, a1 groups them behind a single /skills command that opens a searchable dialog. To jump straight to one, type /skills: followed by its name; typing : on the highlighted /skills row does the same.

Prefer every skill as its own command? Set Skills to expand in /settings → Agent to list each one as /skill:<name>.

Prompt templates

Any Markdown file in ~/.a1/agent/prompts/ or the project's .pi/prompts/ becomes a slash command named after the file.

# ~/.a1/agent/prompts/review.md  →  /review
Review the staged changes for bugs, missing tests, and unclear names.

Run /reload after adding or editing skills and templates.

Settings & files

/settings holds a1's own options first, followed by the pi engine settings that apply inside a1.

a1 settings

Useful pi settings in the same screen include auto-compact, image display, Mermaid diagrams, default project trust, double-escape action, and Fullscreen copy on select. a1 always uses its dark theme, so the theme setting is hidden.

Files and locations

After editing any of these by hand, run /reload.

Environment variables

Updates

a1 tells you when a new release is out. It never installs anything on its own.

Update commands

Updating does not interrupt other a1 windows; they keep running their current version until restarted. Updating within a channel never downgrades.

Update notice

At most once a day, a1 checks npm for a newer release on its channel at startup and shows a banner with the command to run. Close it with its ✕. Release builds suggest a1 update; preview builds suggest a1 update --develop.

Turn the check off with Update check in /settings → Generic, or set A1_SKIP_VERSION_CHECK=1. It is also skipped in CI and when output is not a terminal.

What's new

After an update, a1 shows the release notes once at startup. Read them again any time with /changelog.

CLI reference

a1 is interactive. Its command line starts sessions and manages the install; everything else happens inside the app.

Commands

Interface

a1 replaces pi's interface with a fullscreen view built for long sessions: a scrolling transcript above a fixed input dock, with the details you check most kept in sight.

Following output

The view follows new output as it streams. Scroll up to read earlier work and it stops following; a floating Jump to bottom (Ctrl+End) ↓ button appears, or N new messages if more has arrived. Press Ctrl+End or click it to catch up.

Prompts in the transcript

• Each prompt you send shows the time it was sent.
• The prompt you are reading under stays pinned at the top while you scroll. Click it to jump back to it.
• Shift+↑ and Shift+↓ jump between your prompts.
• Compacted context appears as a single row, such as Compacted from 281,483 tokens.

Scrollbar

Click or drag the scrollbar to move through long transcripts. Its visibility, thickness, and scroll speed are in /settings → Scroll.

Footer

The first line shows the project path, git branch, a clickable pull request badge when the branch has one, and the session name. The second shows token and cache usage, cost, context fill (amber above 70%, red above 90%), the model, and the thinking level.

Notices

Confirmations, warnings, and errors appear briefly above the editor instead of being added to the transcript, so the conversation stays clean.

Quitting

Quitting plays a short animation and leaves only a dim resume hint in your terminal. Turn the animation off with Quit animation in /settings.

Paste chips

Large pastes, links, files, and images collapse into compact chips in the editor, so your prompt stays readable. The full content is sent when you press Enter.

Kinds of chips

Shorter text is inserted as is.

Editing around chips

A chip behaves like a single character: the cursor steps over it, and one Backspace removes it. Copying editor text copies the full content behind each chip, not the label.

What gets sent

• Text and link chips expand to their full content.
• File and folder chips expand to the path. The agent reads the file with its tools; the contents are not attached.
• Image chips are attached as images.

Images

Paste screenshots with Ctrl+V (Alt+V also works on Windows), or right-click in the editor. Up to 8 images are sent per prompt by default; change this with Prompt image limit in /settings. Providers may accept fewer.

Prompt history

What you type is remembered across sessions and projects, so yesterday's prompt is a few key presses away.

Recall a prompt

Press ↑ at the top of the editor to step back through earlier prompts, and ↓ to come forward. Moving past the newest entry brings back the draft you were writing. The editor border shows your position, for example History 97/100.

History is shared by every session and project that uses the same a1 profile. Repeating a prompt moves it to the front instead of adding a duplicate. Pasted images come back as chips when you recall a prompt.

What is saved

Prompts, follow-ups, steering messages, ! shell commands, and skill or template commands as you typed them. Agent responses, tool output, credentials, and environment values are never saved.

Storage and privacy

History is a local SQLite database in ~/.a1/data/history/, one file per profile. Access is limited to your user account where the system supports it.

Turn it off or clear it

Switch off Persistent history in /settings → History; it applies the next time a1 starts. History limit keeps between 10 and 100 entries.

Turning history off does not delete what is saved. To clear it, close every a1 window that uses the profile, then delete that profile's files in ~/.a1/data/history/.

Next-step suggestions

After a response finishes, a1 can predict what you are likely to ask next and show it as faint text in the empty editor.

Using a suggestion

1. Press Tab to put the suggestion into the editor.
2. Edit it if you like.
3. Press Enter to send it.

A suggestion is never sent by itself: Enter does nothing while only the faint text is showing. Start typing to dismiss it; clear your draft and it comes back.

How it works

a1 makes one extra background request to your selected model at its lowest thinking level. Often no suggestion appears, because the model chooses not to guess. Suggestions disappear when you send, switch session or model, or interrupt.

Turn it off

Switch off Prompt suggestions in /settings → Agent. The change applies immediately.

Selection & copy

Select text in the transcript with the mouse, like in any other app, and copy it without fighting the terminal.

Selecting

• Drag to select. The view scrolls when you drag past the edge.
• Double-click selects a word, triple-click selects a line.
• Selection still works on visible transcript text while a dialog is open.

Copying

A short notice confirms how many characters were copied.

Over SSH

In a remote session, a1 copies through your terminal (OSC 52, up to 64 KiB) when the terminal supports it. It never reads or writes the remote machine's clipboard.

Profiles

a1 and pi keep separate profiles, so trying a1 never touches your pi setup.

Separate from pi

a1 uses ~/.a1/agent; pi uses ~/.pi/agent. a1 does not copy, merge, or import pi's settings, credentials, sessions, packages, or trust decisions. Log in and install extensions in a1 separately.

Both tools can still edit the project files you point them at.

Several windows

Run as many a1 instances as you like in separate terminals. Closing one never closes another, and they share prompt history when they use the same profile.

Moving the profile

Set A1_PROFILE_HOME to use a different home directory for .a1/agent, for example to keep a separate work profile.

Reporting a problem

Include the output of a1 version, your operating system and terminal, and a minimal example when you open an issue. Remove private prompts and credentials first.