Seed Code CLI

Seed Code — Eagox Studio

Faster. Smaller. Smarter. Workspace-aware.

Plant ideas. Grow code.

Seed Code is a premium terminal-based AI coding assistant and task runner. v8.1.0 exposes exactly three modes — Chat Mode, Code Mode and Agent Mode — over a multi-provider, multi-model engine, with project-aware Code Mode and a real Agent Mode execution loop, behind the Seed Code startup logo and a compact block of live session state.

The retired Assist Mode is no longer a separate mode; its capabilities now belong to Agent Mode. /assist and /desktop remain accepted aliases, but nothing in the UI presents a fourth mode.

• Providers: choose OpenRouter, Ollama (started automatically when you select it), or any number of your own Custom OpenAI-compatible providers with /provider. Custom configurations are saved without limit, each with its own name, base URL, key and model.
• Reliable by design: provider health is tracked, a failing request fails over to the next healthy provider without restarting the task, and a lost connection pauses the session instead of failing it.
• Professional startup screen: the Seed Code ANSI logo with the live provider, model, mode and status beneath it, behind a responsive bordered panel, with an ASCII fallback for consoles that cannot draw the block art.
• Step-by-step tasks: Code Mode shows the real plan as a live checklist, and Agent Mode shows an event-driven step flow — both reflect what the agent really did, and hand the prompt back when the task ends. Completing a task never closes the application.
• Version: 8.1.0 (seedcode --version)

Installation

After any installation method, seedcode is the primary command:

seedcode

pip (any platform)

pip install seedcode-cli

Requires Python 3.10 or newer. The wheel exposes the seedcode console script; python -m seedcode also works as a developer fallback.

Seed Code CLI is also distributed through the official IRM installer system and GitHub Releases. The installers download the official release artifact for your platform, verify its SHA256 against the release's SHA256SUMS.txt, and then verify the installed command.

Windows

PowerShell 5.1 or newer:

irm https://seedcode-cli.vercel.app/install.ps1 | iex

Installs for the current user (no administrator rights, no Python) into %LOCALAPPDATA%\Programs\SeedCode, adds seedcode to your user PATH, and prints the verified version when it finishes.

Linux

curl -fsSL https://seedcode-cli.vercel.app/install.sh | bash

Installs for the current user. No prebuilt Linux/macOS binary is published in this release: install.sh installs the official Python wheel from the same release with pip install --user, so it needs Python 3.10 or newer (with pip) on the machine. If a prebuilt binary for your platform is ever published, it is used directly instead. Either way install.sh installs only what it can verify against the release's SHA256SUMS.txt — a missing checksum entry, a mismatching digest, or a host with no SHA256 tool makes it stop instead of installing unverified code.

Windows installer (GUI alternative)

The release publishes two Windows binaries; both are fully self-contained (no Python required) and both run the same CLI:

Both are published on the Releases page with their SHA256 in SHA256SUMS.txt.

After installing by any route:

seedcode --version    # -> Seed Code CLI 8.1.0

seedcode not recognized? Open a new terminal. PATH changes only apply to fresh sessions; the installers verify this before they finish.

From source (development)

Requires Python 3.10 or newer:

git clone https://github.com/Alshahriar-07/seedcode-cli.git
cd seedcode-cli
python -m pip install -e ".[dev]"
seedcode

First run

seedcode

You land on the Seed Code dashboard — the structured startup panel: branding on the left, a divider, and the live session state on the right. The ASCII logo is permanently gone (the brand is plain text); the layout, sections and status indicators stay:

╭─ Seed Code CLI v8.1.0 ───────────────────────────────────────────────────────────────────────╮
│                                                                                              │
│   Seed Code                                │ Seed Code  |  Eagox Studio                      │
│   AI CODING AGENT                          │ Plant ideas. Grow code.                         │
│                                            │ Provider   Default                              │
│                                            │ Model      cohere/north-mini-code:free          │
│                                            │ Mode       Chat  •  ● Ready                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
Commands  /help  /status  /codemode  /agent  /provider  /model
You >

The panel is 96 columns wide on a wide terminal — wide enough that the whole cohere/north-mini-code:free model name fits without clipping — and kept deliberately short (one blank row under the title, then the live rows; no padding rows to scroll past). Narrower terminals slide the info section left so the whole model name still fits (80 columns shows it in full), then fall back to a compact one-row panel, then to plain lines. Consoles that cannot draw (or encode) the glyphs get the same layout in ASCII.

The API Key row appears only for providers that actually require a key, so Default and Ollama never show one. cohere/north-mini-code:free is the ships-with default for Default only; every other provider keeps its own model, and switching providers never copies one model onto another.

Default provider (no API key)

Default is Seed Code's built-in API connection and the provider the app ships with. It is a first-class provider of its own — separate from OpenRouter everywhere: its own entry in /provider, its own saved model, its own status, and its own credential slot. It resolves its credential itself, in this order:

1. a key stored in Default's own slot (advanced/manual use);
2. the embedded Seed Code release credential (release artifacts only);
3. OPENROUTER_API_KEY / SEEDCODE_DEFAULT_API_KEY in the environment.

It never reads or writes another provider's configuration, and no other provider inherits Default's credential. If a build carries no built-in credential (a source checkout, for example), Default says so plainly instead of failing with an authentication error — pick OpenRouter and add your own key.

Your own API key

Use /apikey (view / replace / remove / validate) or set an environment variable:

export OPENROUTER_API_KEY="sk-or-..."      # PowerShell: $env:OPENROUTER_API_KEY = "..."
export FREEMODEL_API_KEY="fe_oa_..."
export AEROLINK_API_KEY="..."

Keys are validated with a real authenticated request before they are saved. They are stored per provider in ~/.seedcode/config.json, never in any project directory, and never printed, logged, or included in an error message.

Providers

Every provider is fully independent: its own API key, model, settings, and connection status. Switching providers never touches another one's configuration.

Switch with /provider — the picker groups choices by what they need (Built-in · no API key, Your own API key, Local) and shows each provider's backend, current model, and key state. Pick models with /model (OpenRouter filters free vs pro models; FreeModel offers Auto mode).

Agent Mode and permissions

Agent Mode lets the model act on your project through the tool engine: a multi-step task that uses real tools, verifies what it did, and reports what actually happened instead of claiming success:

/agent on

Permission modes (view/set with /permission):

Code Mode

Code Mode is a real coding agent for the current project. Your working directory becomes the workspace:

/codemode on        # treat the CWD as the workspace, enable .seedcode memory
/codemode off       # back to the previous mode (memory stays on disk)
/codemode status    # workspace, memory, and index state

In Code Mode the agent consults the project index, finds relevant files with targeted searches, reads only what it needs, plans, edits, runs a relevant command or test, and reports what changed. File operations stay inside the workspace root.

Persistent task execution

Code Mode is a long-running agent, not one model call. A request becomes a plan (a task graph with dependencies and acceptance criteria), and the session runs task after task until each one is verified:

Plan (3 tasks) → Task 1 → verify → Task 2 → verify → Task 3 → verify
              → final verification → project complete

• A response is not completion. A task is only COMPLETED when its acceptance criteria are satisfied by real evidence — files that exist, a command that ran and exited 0, tests that passed, no unresolved error. A model that says “done” while the tests fail is sent back to fix them.
• A task is a unit of work, not a model call. Each task may take many model/tool cycles: analyse → inspect → implement → run → fail → fix → re-run → verify.
• Limits do not end a task. An output/context limit continues the task with another call; a temporary provider error retries with backoff; a repeated identical failure stops with an explicit blocker instead of looping.
• State survives. Every transition is checkpointed to .seedcode/checkpoints/, so a pause, a crash or an API failure resumes from the current task.

/session   # the detailed view: session state + one row per task record
/pause     # stop at the next safe boundary, keeping plan + files
/resume    # continue from the checkpoint (current task, not from zero)
/stop      # safely end the autonomous session

Ctrl+C stops the session the same way; nothing here closes an application or rolls back your files. A stopped session is not lost: the CLI says so and /resume continues from the checkpoint.

Every task also keeps its own execution record — files inspected and affected, commands run with their outcome, tool calls, test results, errors, retries, timestamps and the verification result — and it is stored per task in .seedcode/plan.json, so a resume continues with the full per-task history. /session renders that record:

State            RUNNING
Progress         1/3 tasks verified
Current task     2. Create database
Action           Running pytest tests/db
Model calls      12
Tool calls       31
Tests            passed (pytest -q)
Commands         1/1 ok
Files changed    1
Files inspected  2
Checkpoint       saved on pause/stop (see /resume)

✓ 1  Setup project    verified 2 criteria  1 inspected; 1 file(s); 1/1 cmd ok; tests passed
● 2  Create database  —                    no tool activity recorded
○ 3  Add tests        —                    not started

/status carries the same state in one line (Session RUNNING (1/3 verified) — Task 2), and a stopped one reports that it is resumable. A task row only ever shows what was observed — a task that did nothing reads no tool activity recorded, never a success.

.seedcode project memory

Enabling Code Mode creates a .seedcode/ directory in the project root:

my-project/
├── .seedcode/
│   ├── memory/       durable project knowledge (architecture, decisions…)
│   ├── index/        per-file summaries + a file map (incremental, hashed)
│   ├── context/      reusable project context (conventions, snippets)
│   ├── sessions/     compact per-session summaries (never raw transcripts)
│   ├── checkpoints/  resumable Code Mode session state
│   ├── plan.json     the current task graph
│   └── config.json   safe project configuration
├── src/
└── ...

• Incremental indexing — every indexed file is hashed; only changed files are re-summarized on the next run.
• Secrets never land here — writes pass a secret-key filter; API keys, tokens, and passwords are rejected at write time.
• Not source code — .seedcode/ is excluded from workspace search, indexing, and the agent's project view.

Task flow (Code Mode / Agent Mode)

Every task in Code Mode or Agent Mode is shown as a compact live flow, and each step changes state only when the work behind it really happened. Code Mode shows the protocol header, the plan as a checklist, and a single live action line:

╭─ SEEDCODE 8.1.0 • CODE MODE ────────────────╮
│ ● RUNNING   Task 3/8   Build authentication │
│   ████████████░░░░  72% • 4m 32s • 18 calls │
│ → Running: pytest tests/auth                │
╰─────────────────────────────────────────────╯
✓ Setup project
✓ Create database
● Implement authentication
○ Build dashboard
○ Add tests

The action line is a real phase, not decoration: it shows the tool actually running (reading a file, editing one, running a command), and it switches to Verifying acceptance criteria / Verifying the project (tests / build) when the session moves into those phases. The panel re-fits itself on every refresh, so resizing the terminal mid-session cannot leave a panel wider than the screen — it degrades to a single status line when the space runs out.

Agent Mode keeps the event-driven step flow:

Task  ·  Code Mode
Fix authentication persistence
✓ Analyze project  request understood
✓ Inspect files  read_file seedcode/config.py
✓ Plan implementation  I'll patch the persistence layer…
● Implement changes  edit_file seedcode/config.py
○ Run tests
○ Verify result
  Working…

The five states are pending, running, completed, failed and skipped. A step the task never needed is reported as skipped — “Run tests” is never marked done unless a recognised test command actually ran, and a failing run is shown as failed, showing what failed instead of a passing count:

✓ Task completed
  2 file(s) changed: seedcode/config.py, seedcode/providers.py
  Tests: 898 passed — pytest tests -q
Ready for next task.

A whole Code Mode project closes with the evidence that verified it, not a restatement of the model's replies:

✓ Project completed — 3/3 tasks verified
  ✓ Verification: accepted
  ✓ Tests: passed
  ✓ Files: 4 affected
  ✓ Commands: 7/7 ok
  • Inspected: 12 item(s)
Ready for next task.

✗ Task failed  —  tests failed
  1 step(s) failed: Run tests
Ready for another task.

A task never closes the CLI: success, failure and Ctrl+C all return to the prompt (or the menu) so you can inspect the result, run another task, switch mode or provider, or /exit yourself. Plain Chat Mode is unaffected — it answers with the ordinary spinner.

Terminal execution

The agent runs commands through the tool engine's run_command tool:

• output streams line-by-line while the command is still running, so long builds and test runs stay visible instead of blocking. The live view is compact: the first few lines of each command are echoed, then one summary line. The agent and ~/.seedcode/logs/seedcode.log still receive the full output, and failures are never hidden;
• stderr is captured along with stdout, in order;
• the exit code is reported, and a non-zero exit is an explicit failure the model can react to;
• commands have a bounded timeout (default 60s, up to 300s) and a timeout kills the whole process tree;
• Ctrl+C cancels the running command — its process tree is terminated — and the agent turn continues with the cancellation reported as a failed result;
• shells: cmd, powershell, pwsh, bash, or auto (the shell you are actually in), on Windows and Linux.

Command reference

Keyboard shortcuts: Ctrl+K command palette, Ctrl+P project file search, Ctrl+R history, Ctrl+, settings, Ctrl+/ shortcut reference, Ctrl+L clear.

All exit paths are clean: /exit → menu, menu → Exit, Ctrl+C (cancels a response or the current line), and Ctrl+D/EOF. No traceback appears on normal exit.

Desktop control

With the desktop/full_system permission level, Seed Code can inspect windows, resolve UI elements semantically (accessibility tree, OCR, and image refinement — no brittle coordinates), launch and focus applications, and drive keyboard/mouse with per-action verification. Waits are state-based: open_app polls for real window evidence instead of sleeping, verification pauses are short because state is re-read live, and screenshots are taken only when information is genuinely needed.

Applications stay open. When Seed Code opens an application or a browser to do something for you ("play this song"), the app remains open when the task finishes. Closing is only ever done on an explicit request (close_app / browser_close); no teardown, retry, or cleanup path may close a window, a browser, or a tab behind your back. Internal cleanup (releasing mouse/keyboard control, closing DevTools sockets, dropping cached drivers) is unchanged, and Seed Code never closes its own terminal — /exit does that.

Configuration and local data

~/.seedcode/
├── config.json       provider and application settings
├── history/          saved conversation sessions (per provider)
├── memory/           persistent local memory
└── logs/             rotating diagnostic logs

config.json keeps one isolated entry per provider:

config.json
├── active_provider
├── providers
│   ├── default          { api_key(unused), model }
│   ├── openrouter       { api_key, model }
│   ├── freemodel_claude { api_key, model }
│   ├── freemodel_codex  { api_key, model }
│   ├── aerolink         { api_key, model }
│   └── ollama           { api_key(unused), model }

Switching providers loads that provider's own key and model, and saving one provider never overwrites another's. Credentials stay local; environment variables take precedence over stored keys. Logs never record API keys or message content. /doctor checks configuration, connectivity, and provider health.

Platform support

• Windows: full experience — desktop control, one-click installer, standalone EXE. Primary platform.
• Linux / macOS: terminal chat, providers, project tools, Code Mode. Install with the install.sh command above — it installs the official Python wheel, so Python 3.10+ (with pip) is required. No prebuilt Linux/macOS binary is published in this release.

Building from source

Python distributions

python -m pip install build twine
python -m build          # wheel + sdist, version read from seedcode/__init__.py
python -m twine check dist/*

Windows EXE + installer

scripts\windows\build.bat

Stage 0 generates the branding assets (icon, wizard art, exe version resource). Stage 0b embeds the default API configuration from a local .env (git-ignored; skipped when absent — never printed or committed). Stage 1 builds the self-contained dist\seedcode.exe with PyInstaller (icon + version resource embedded) and verifies it. Stage 2 compiles the Inno Setup installer and verifies it. Stage 3 stages everything into dist\release\<version>\ and writes SHA256SUMS.txt with real hashes. Every stage fails loudly on a version mismatch, so a stale binary can never ship.

Details: scripts/windows/README.md.

Release artifacts (v8.1.0)

Release: v8.1.0

Built artifacts are collected in dist/release/8.1.0/ during a release build. Publishing (GitHub Release) is a separate step; the remote installers read the release named v8.1.0.

The remote installers

IRM_INSTALL/ is the source of the scripts served at https://seedcode-cli.vercel.app:

Troubleshooting

• seedcode is not recognized — open a new terminal after installing; PATH changes only apply to fresh sessions. The installer verifies this before it finishes.
• "Setup needed" on the header — the active provider is not usable yet. Run /provider. Default needs a built-in credential (release builds have one); OpenRouter/FreeModel/AeroLink need your own key.
• Default says the built-in connection is unavailable — this build has no embedded credential. Run /provider and choose OpenRouter, or set OPENROUTER_API_KEY.
• 401/403 errors — your key is invalid or lacks access; /apikey to replace it, /doctor for diagnostics.
• 402 errors — the model needs credits; /model and pick a free model (Default ships with cohere/north-mini-code:free).
• Rate limits (429) — wait and retry; Seed Code honors the provider's Retry-After hint. Consider a different provider.
• Desktop actions fail — check /permission (desktop requires the desktop level) and /computer for engine status.
• Reset everything — delete ~/.seedcode/ (settings, keys, history); .seedcode/ project memory lives in each project and is separate.

Security model

• Credentials stay local and provider-scoped. Saving or switching one provider never reads or writes another provider's key slot, so a key cannot leak between Default, OpenRouter, FreeModel, AeroLink and Ollama.
• The built-in Default credential is resolved per request and is never copied into another provider's stored configuration.
• Keys are shown masked (sk-or-••••••••) or not at all — never in full, never in logs, never in error messages, never in a release artifact.
• Computer actions pass permission checks, verification, and retry limits.
• .seedcode/ memory refuses secret-looking fields at write time.
• The release build consumes the local .env only during packaging; the secret never enters source control, logs, manifests, or package metadata.

Review permissions before enabling Agent Mode — especially in unfamiliar projects or with sensitive applications.

Credits

• Created by: Al Shahriar Sowan — https://alshahriarsayon.vercel.app/
• Studio: Eagox Studio — https://eagoxstudio.vercel.app/
• Contact: seedcode.ai@gmail.com

License

Seed Code CLI is licensed under the PolyForm Noncommercial License 1.0.0 (PolyForm-Noncommercial-1.0.0) — free for personal learning and other noncommercial use; commercial use is not permitted. See LICENSE for the full terms.