Important
Unofficial — a community-driven exploration. Step Pilot originated from a snapshot of stepfun-ai/Step-Realtime-CLI (step-code-explore-pi at db7dd58, 2026-08-21) and has been independently maintained and substantially evolved since 2026-09-02.
A terminal coding agent CLI optimized for Step 3.7 Flash stability. It ditches the heavy prompt stack and bloated context budget that make small models fail: a ~2000 char system prompt, tighter tool-result caps, and earlier compaction let Flash actually follow instructions — without giving up the agent loop, sub-agents, or plugin system when you need them.
Small frontier models are fast and cheap, but they break under the weight of traditional agent scaffolding: long system prompts, runaway tool outputs, and lazy compression eat the context window before the real work starts.
step-pilot treats small-model instruction following as a first-class constraint:
- ~2000 char system prompt — the smallest useful instruction set, not a kitchen-sink manifesto
- Tool results capped at 400K chars — stops one runaway command from drowning the model
- Compaction triggers earlier, keeps less — default trigger at 75% context, retains the last 6 messages during summary; user messages get a 20K token fidelity budget
- Clearer tool contracts — core tool descriptions rewritten for unambiguous instruction following
The point isn't to make Flash behave like a 700B model. It's to stop wasting its context on things that don't matter, so the instructions that do matter actually get followed.
step-pilot is a terminal coding agent CLI. The model uses tools to read and write real files, run real commands, and spawn sub-agents; results feed back into the loop until the task is done.
It's built with pi-tui and speaks three protocols — Anthropic Messages, OpenAI Chat Completions, OpenAI Responses — so any compatible provider works out of the box. Step is the default and best-tested path.
First run is interactive — it walks you through API key, provider, and model selection. No manual config editing required.
Artifacts are distributed through GitHub Releases, not the npm public registry. Install the latest release tarball with npm:
npm i -g https://github.com/Zi-Yi-Ming/step-pilot/releases/latest/download/step-pilot.tgz
step-pilotRequires Node.js >= 22. Without Node, grab the standalone executable for your platform from Releases; to modify the code, install from source instead.
See Quick start for installation and configuration details, and Installation for the trade-offs between installation methods.
If you already have another AI agent at hand, skills/step-pilot-install/ is an install-instructions skill: clone the repo, point your agent at it, and it will know how to build, where to put the API key, and what to check when the build fails.
English documentation lives under docs/en/; the Chinese originals under docs/ are the source of truth.
| Document | Contents |
|---|---|
| Quick start | Install, set the API key, first conversation |
| Installation | Requirements, building from source, global command, upgrade and uninstall |
| Configuration | Every config.toml field, multi-protocol providers and model aliases, environment variables, data directories |
| Interactive use | TUI layout, slash commands, keybindings, the three permission tiers, plan mode, switching model and provider |
| Tools | Parameters and behavioral limits of every built-in tool, parallel execution and result feedback |
| Sub-agents and automation | spawn_agent, dynamic_workflow, autonomous goals, scheduled tasks, background tasks |
| Session management | Persistence, resuming, forking, context compaction, review, non-interactive output |
| Skills, plugins, and MCP | SKILL.md format, loading precedence, plugins, MCP integration |
| Hooks | Running shell commands at five lifecycle events |
| Step 3.7 Flash best practices | How to get the most out of step-pilot with small models |
Source layers: config → provider → tools → agent (the loop) → tui-pi (pi-tui) → cli.ts (entry); main.ts is only the bin bootstrap (sets NODE_ENV, then loads cli.js).
pnpm dev # run directly with tsx, for interactive development
pnpm typecheck # tsc in strict mode
pnpm test # vitestCI runs typecheck, build, and test on Ubuntu, Windows, and macOS. Development conventions and the rules for model integration are in AGENTS.md; the contribution process is in CONTRIBUTING.md.
Step Pilot is built on the pi open-source ecosystem — its TUI/agent shell uses @earendil-works/pi-tui (packages/tui of the pi repository) — and originated from a snapshot of the stepfun-ai Step-Realtime-CLI step-code-explore-pi exploration branch. This project independently fixes upstream issues and re-tunes the agent for small models such as Step 3.7 Flash; it is not affiliated with, sponsored by, or endorsed by earendil-works, stepfun-ai, or any other third-party project. Third-party open-source license texts are collected under licenses/ for compliance, with details in licenses/NOTICE.md.
MIT, see LICENSE. Third-party acknowledgements and licenses are under licenses/.