Install
Release:
npm x -y -- @timurproko/a1-install
Develop:
npm x -y -- @timurproko/a1-install --develop
Preview number:
npm x -y -- @timurproko/a1-install --develop 107
Exact preview:
npm x -y -- @timurproko/a1-install --develop 0.1.8-dev.107
Launch
Launch A1 (profile: ~/.a1/agent):
a1
Launch A1 in single agent mode:
a1 solo
When a solo session exits, its printed a1 solo --session <id> command resumes that same conversation in solo mode; a custom session store is included in the printed command. Resident tabs are different: they keep running after detach, and bare a1 returns to them.
Show all commands:
a1 help
Show the current and latest versions:
a1 version
Vanilla Pi oracle (~/.pi/agent):
a1 pi
Tabs
Tabs keep running after their terminal closes. List them, or stop one; its session stays resumable:
a1 tabs
a1 tabs stop <id>
Stop every tab and the resident host when you are finished with them (not required to run a1 solo):
a1 tabs host stop
Show host health, or write a redacted diagnostic bundle:
a1 tabs host status
a1 tabs doctor
Update
Install the release:
a1 update
Install develop:
a1 update --develop
Install preview 107:
a1 update --develop 107
Install that exact preview:
a1 update --develop 0.1.8-dev.107
Refresh A1's model catalogs:
a1 update --models
Stuck on 0.2.2 and a1 update fails? Run the installer once, then use a1 update as usual:
npm x -y -- @timurproko/a1-install
The Update setting controls release discovery:
- Auto (default) checks the running release's stable or development channel at startup and every 15 minutes while open. It silently installs a verified update, then shows
Update installed · Restart to update; existing sessions keep running until restarted.
- Notify checks at startup (at most daily), keeps the
Update Available notice, and leaves installation manual.
- No performs no update check; updates remain available through the commands above.
A1_SKIP_VERSION_CHECK=1 disables both Auto and Notify discovery. Manual stable, development, and exact-version update commands remain available in every mode.
Extensions
Install a package:
a1 install npm:pi-mcp-adapter
Remove it (alias: a1 uninstall):
a1 remove npm:pi-mcp-adapter
List installed packages:
a1 list
Update every installed package:
a1 update --extensions
Update one:
a1 update npm:pi-mcp-adapter
Develop
A source build needs Node.js, npm, git, and Rustup. Windows additionally needs Visual Studio or Visual Studio Build Tools with the Desktop development with C++ workload, MSVC x64/x86 tools, and a Windows SDK; Visual Studio Code is not required. A1 discovers installed Rustup and Visual Studio tools and initializes them for build children, so Git Bash and ordinary PowerShell do not need manual PATH or developer-shell setup. It never installs these tools or accepts their licenses automatically.
Install exact locked dependencies:
npm ci
Compile TypeScript and the native addons into dist:
npm run build
Build and launch a source a1:
npm start
Build and launch a source a1 pi:
npm run start:pi
Typecheck + fast suite (alias: npm test):
npm run test:fast
Complete non-physical suite:
npm run test:full
Report Node, npm, git, Rust, dependency, and Windows C++ readiness. Missing Windows tools are listed in setup order; after installing them, rerun the same build command:
npm run doctor
Preview the README as GitHub renders it, in your browser (needs gh):
npm run preview:readme
Publish
Develop
Request the preview publish:
npm run develop
Release
npm run release -- patch # 0.1.8-dev -> 0.1.8
npm run release -- minor # 0.1.8-dev -> 0.2.0
npm run release -- major # 0.1.8-dev -> 1.0.0
npm run release -- 0.4.0 # prepare an exact stable version
Once validation passes, open the printed draft link, edit the ## [version] - YYYY-MM-DD changelog, and press Publish release to publish to npm. Details: release runbook.
