AstraCode v1.0.2

AstraCode is an agentic coding CLI with a planner/executor architecture, provider-first model selection, local-runtime support (Ollama and llama.cpp), and an in-terminal TUI optimized for real coding workflows.

It is designed for a hybrid setup:

Planner model for deeper reasoning and task decomposition.
Executor model for fast file edits and command execution.
Tool loop for shell, file, git, diagnostics, and web search actions.

What AstraCode does
Core features
Architecture
Install and setup
Running AstraCode
Configuration reference
Provider and model management
Interactive TUI and keybindings
AstrAPI for remote/local GPU serving
Tooling behavior
Verification and git workflows
Developer scripts and testing
Troubleshooting
Version notes
License

What AstraCode does

AstraCode accepts natural-language coding requests, routes them to the right role (planner or executor), and performs end-to-end implementation using tools:

edit/write files
run shell commands
inspect diagnostics
search the codebase
use internet search when needed
run git operations

The output in chat is rendered with Markdown-aware code block styling, and file changes are shown in a dedicated in-place change review panel.

Core features

Feature	Description
Smart router	Auto-decides planner vs executor based on request complexity.
Role-specific prompting	Planner and executor each use dedicated prompt behavior.
Provider-first model picker	`/model-plan` and `/model-exe` open provider-first model selection with filtering and scrolling.
Multi-provider support	Works with OpenAI-compatible providers (NVIDIA, Google, OpenRouter, Hugging Face, xAI, etc.).
Multi-language coding	Uses requested language or infers from project stack/necessity (Python, Java, C, C++, Go, Rust, TS/JS, etc.) instead of forcing one default.
Local runtime options	Native support for Ollama and llama.cpp execution paths.
AstrAPI integration	Connect to local/LAN OpenAI-compatible endpoint for remote GPU workflows.
Code-style output rendering	Shell and git outputs are shown in readable code-block style panels.
Change review panel	File edits update OLD/NEW review panel, navigable with `[` and `]`.
Verification guardrail	Optional auto-verify command after edits (`/verify`).
Auto peer review pass	For substantial/risky edits, AstraCode runs a git-diff peer review pass before finalizing.
Disposable shell session	`/cmd` and agent shell calls share a conversation-scoped working directory (`cd` persists until session ends).
Context efficiency guard	Long sessions are compacted to recent high-value context to keep task execution fast and stable.
Built-in git controls	`/git status`, `/git diff`, `/git commit` plus aliases.

Architecture

High-level flow

User enters prompt in TUI.
Router chooses role (planner or executor) when mode is auto.
Agent loop calls tools as needed.
Tool outputs stream into chat with styled rendering.
File changes are reflected in change-review panel.

Roles

Planner
- best for architecture, decomposition, multi-step strategy
- typically a stronger reasoning model
Executor
- best for concrete implementation, file edits, command execution
- can be a faster local model

Routing modes

auto (recommended)
planner-only
executor-only

Switch with slash commands:

/router auto
/router planner-only
/router executor-only

Install and setup

Prerequisites

Node.js 20+ recommended
npm 10+
Git
Optional runtimes:
- Ollama
- llama.cpp (llama-server)

Install from repository

git clone <your-repo-url>
cd astracode_main
npm install
npm run build

Global command install

npm run install:global

This links:

astracode (main CLI)
astrapi (node_runner launcher)

Windows alias helper (PowerShell)

npm run alias:install

Then restart the terminal.

macOS alias auto-install

On macOS, npm install now auto-runs alias setup and inserts an astracode shell function into ~/.zshrc and ~/.bashrc (idempotent marker block).

You can also run it manually:

npm run alias:install:macos

Running AstraCode

Normal chat

astracode

or

astracode chat
astracode chat "Create a TypeScript script that parses CSV and run it"

Runtime override options

astracode chat --ollama
astracode chat --ollama qwen3.5:latest
astracode chat --llama
astracode chat --llama DeepSeek-R1-Distill-Qwen-7B-Q4_K_M.gguf
astracode chat --astrapi http://192.168.1.10:19090/v1

Dev scripts

Use these instead of awkward npm arg forwarding:

npm run dev:chat
npm run dev:ollama
npm run dev:llama
npm run dev:astrapi

If you use npm run dev directly:

npm run dev -- chat -- --ollama qwen3.5:latest

Configuration reference

Default config location:

Windows: %USERPROFILE%\.astracode\config.json
macOS/Linux: ~/.astracode/config.json

Example config

{
  "providers": {
    "nvidia-plan": {
      "baseUrl": "https://integrate.api.nvidia.com/v1",
      "model": "minimaxai/minimax-m2.7",
      "apiKeyEnv": "NVIDIA_API_KEY"
    },
    "ollama-executor": {
      "baseUrl": "http://127.0.0.1:11434/v1",
      "model": "qwen3.5:latest",
      "apiKeyEnv": ""
    }
  },
  "routing": {
    "mode": "auto",
    "planner": "nvidia-plan",
    "executor": "ollama-executor"
  },
  "settings": {
    "verboseToolOutput": false,
    "liveToolRendering": true,
    "confirmDestructiveCommands": true
  },
  "verification": {
    "enabled": false,
    "command": "npm test"
  }
}

Environment variables

Set provider keys in your shell profile, or place them in a workspace .env file (auto-loaded by AstraCode):

NVIDIA_API_KEY=...
GOOGLE_API_KEY=...

Example .env:

NVIDIA_API_KEY=your_key_here
GOOGLE_API_KEY=your_key_here

On startup, AstraCode auto-registers the built-in Gemini provider when GOOGLE_API_KEY is present and no Gemini-family provider is already configured.

Only keys referenced by apiKeyEnv are required.

Provider and model management

Recommended free baselines

If you want a fast default setup with free-tier endpoints:

Role	Provider	Recommended model
Planner	NVIDIA (`nvidia-plan`)	Use the top `[free]` model from `/provider test nvidia-plan`
Executor	OpenRouter (`openrouter`)	`google/gemma-4-31b-it:free`

GOOGLE_API_KEY auto-registers gemini with gemini-2.5-flash as its default model.

Command palette model flow

When you type /model-plan or /model-exe and press enter:

AstraCode shows provider families first (nvidia/gemini/openrouter/huggingface/xai/...).
After choosing a provider, it shows the discovered model pool from configured provider APIs, then applies the selected model to the chosen backend.
Type to filter.
Use arrow keys to scroll through the full list.
Free-tier endpoints (when provider metadata exposes pricing/free-tier tags) are marked with [free].
Press enter to apply.

Escape behavior:

Esc in model list: back to provider list.
Esc again: close picker.

All slash commands

Command	Description
`/help`	Show all available commands
`/status`	Show planner, executor, routing, session info
`/monitor`	Show AstraCode workload and CPU/memory usage
`/config`	Print full JSON configuration
`/verbose`	Toggle verbose tool output on/off
`/live on\|off`	Toggle live tool/result rendering in chat
`/confirm on\|off`	Toggle confirmation before destructive commands
`/verify on\|off\|status`	Control auto verification after file edits
`/verify cmd <command>`	Set verification command (default: npm test)
`/provider list`	List all registered providers
`/provider add <name> <url> <model> [apiKeyEnv]`	Add an OpenAI-compatible provider
`/provider test <name>`	Test provider connectivity and model catalog
`/provider use <planner\|executor> <name>`	Assign a provider to a role
`/provider set url <name> <url>`	Set remote URL for a provider
`/astrapi connect <name> <url> [model]`	Register AstrAPI endpoint as provider
`/astrapi test <name>`	Test a registered AstrAPI provider
`/astrapi list`	List local/LAN-style providers
`/router auto`	Enable automatic smart routing
`/router planner-only`	Force all requests to planner
`/router executor-only`	Force all requests to executor
`/model-plan <model>`	Set planner model (no arg: list available models by provider)
`/model-exe <model>`	Set executor model (no arg: list available models by provider)
`/model planner <model>`	Legacy alias: change planner model
`/model executor <model>`	Legacy alias: change executor model
`/init`	Initialize `.astracode` workspace metadata in current directory
`/learn [focus]`	Generate/update `.astracode/learn.md` project design context
`/plan status`	Show pending implementation plan status
`/plan open`	Open pending implementation plan in your default editor
`/plan accept [index\|plan-id]`	Accept pending plan or choose a saved plan from `plan/`
`/plan reject`	Reject and clear pending implementation plan
`/plan <idea>`	Draft a plan immediately for the provided idea
`/models`	List available models from all configured provider APIs
`/workspace`	Set workspace directory `<path>`
`/workspace show`	Show current workspace path
`/git status`	Show git working tree status
`/git diff`	Show git diff (unstaged by default)
`/git commit <message>`	Commit all changes with a message
`/diff`	Alias for `/git diff`
`/commit <message>`	Alias for `/git commit <message>`
`/cmd <command>`	Run a native shell command directly
`/clear`	Clear the screen / reset UI
`/exit`	Quit AstraCode
`/quit`	Quit AstraCode

No-argument behavior:

/model-plan and /model-exe open interactive selection.
/models lists discovered models from configured provider APIs.
/init creates a workspace .astracode/ folder and registers .astracode/learn.md as always-on context.
/learn [focus] generates/updates .astracode/learn.md (design-context document) for the current directory.
/plan <idea> drafts a plan immediately (saved under plan/), attempts to open it in your system default editor, and waits for /plan accept or /plan reject.
/plan accept now browses saved plans when no pending in-memory plan exists, listing newest first.
/plan accept <index|plan-id> executes the selected saved plan from plan/.
Website/scaffold-style requests can auto-approve and execute staged plan tasks, creating folder structure and starter files automatically.
/monitor shows live AstraCode workload plus CPU/memory/runtime telemetry.
Complex implementation requests now stage detailed markdown artifacts under plan/ using objective + session-linked names (for example: plan/<objective>__<session>__<timestamp>.plan.md and .tasks.md) and wait for /plan accept before execution.

Interactive TUI and keybindings

Main layout

Header: app version, session, workspace, active planner/executor backend + model
Conversation panel: scrollable middle viewport for full user/assistant/tool history
Palette: slash command and model picker
Change review panel: in-place OLD/NEW diff summary for file edits
Status bar: route/activity hints

Keybindings

Key	Behavior
`Enter`	Submit prompt / confirm picker choice. In command palette, auto-completes partial slash commands first.
`Tab`	Accept inline autocomplete suggestion (commands, provider names, model names)
`↑` / `↓`	Navigate picker items; when picker is closed, recall previous/next input history
`Esc`	Close picker / step back in model picker / switch Insert → Normal (vim mode)
`PageUp` / `PageDown`	Scroll chat viewport up/down
`Ctrl+U` / `Ctrl+D`	Fast chat scroll up/down
`Home` / `End`	Jump chat scroll to oldest/newest
`i`, `a`, `A`, `h`, `l`, `0`, `$`, `w`, `b`, `x`, `d{w,b,d}`, `j`, `k`	Vim-style normal mode editing/navigation
`[` / `]`	Navigate previous/next file-change preview
`a`	Accept current change review (hides it from panel)
`Ctrl+L`	Clear screen and redraw
`Ctrl+C`	Exit guard: requires 3 presses within short window to quit

When command execution confirmation is enabled (/confirm on), shell commands require explicit y/n approval before running.
If /cmd exits non-zero, AstraCode now launches an automatic recovery pass to diagnose/fix and re-run.
By default, AstraCode uses the directory where you launched it as the active workspace (not a predefined path).
/cmd now uses a disposable shell session: cd updates session cwd and subsequent commands run from that directory for the rest of the active chat.

Ctrl+C now intentionally prevents accidental immediate exits:

Press 1: warning
Press 2: warning
Press 3: exits

AstrAPI for remote/local GPU serving

astrapi is a lightweight launcher/proxy in node_runner for exposing local runtimes as OpenAI-compatible endpoints.

Typical second-laptop workflow

On GPU laptop, run:
```
astrapi --llama
```
or
```
astrapi --ollama
```
to list models.

On Ubuntu, if llama-server is not in PATH, pass binary path directly:
```
astrapi --llama --llama-bin ~/llama.cpp/build/bin/llama-server
```

Start runtime with selected model:

astrapi --llama <model-file.gguf>

or

astrapi --ollama <ollama-model>

Example (Ubuntu + llama.cpp):

astrapi --llama qwen2.5-coder-7b-instruct-q4_k_m.gguf \
  --model-dir ~/models \
  --llama-bin ~/llama.cpp/build/bin/llama-server

llama.cpp thinking / advanced options

Enable reasoning mode when supported by your llama-server build:
```
astrapi --llama <model.gguf> --thinking auto
```

Pass any additional llama-server flags:

astrapi --llama <model.gguf> --extra-args "--jinja --no-webui"

Environment variable equivalents:
- ASTRAPI_LLAMA_BIN (or LLAMA_CPP_SERVER_PATH)
- ASTRAPI_REASONING_FORMAT (same as --thinking <format>)
- ASTRAPI_LLAMA_EXTRA_ARGS (same as --extra-args)

Copy emitted LAN URL (for example http://192.168.1.44:19090/v1).

On your coding machine:

No token:

astracode chat --astrapi http://192.168.1.44:19090/v1

Token-protected AstrAPI (set key in the same terminal session):

set "ASTRAPI_API_KEY=astracode123" && astracode chat --astrapi http://172.18.54.226:19090/v1

$env:ASTRAPI_API_KEY="astracode123"; astracode chat --astrapi http://172.18.54.226:19090/v1

export ASTRAPI_API_KEY=astracode123 && astracode chat --astrapi http://172.18.54.226:19090/v1

This lets AstraCode use another device's local GPU inference as executor.

Tooling behavior

Registered tools

shell
read_file
write_file
edit
diagnostics
glob
grep
ls
read_files
search_web
git

Shell runner auto-selection on Windows

The shell tool supports:

auto
cmd
pwsh

When auto is used on Windows:

PowerShell-style commands route to pwsh (fallback to Windows PowerShell if needed)
generic commands route to cmd

This improves "generate and run code automatically" behavior without manual runner switching.

Output style

Assistant messages and tool outputs render markdown/code blocks in framed code-style UI, making generated code and command output easier to read directly in chat.

Verification and git workflows

Verification controls

/verify status
/verify on
/verify off
/verify cmd npm run build && npm test

When enabled, AstraCode runs the verification command after file write/edit operations.

Git commands

/git status
/git diff
/git diff --staged
/git commit <message>
/diff
/commit <message>

Developer scripts and testing

package.json scripts

Script	Purpose
`npm test`	Run all unit tests (`tsx --test`)
`npm run build`	TypeScript compile to `dist/`
`npm run dev`	Run CLI entry (`tsx src/cli.ts`)
`npm run dev:chat`	Direct chat boot
`npm run dev:ollama`	Chat with `--ollama` mode
`npm run dev:llama`	Chat with `--llama` mode
`npm run dev:astrapi`	Run `node_runner/astrapi.js`
`npm run install:global`	Link CLI globally (`npm link`)
`npm run alias:install`	Install PowerShell alias helper
`npm run alias:install:macos`	Install/update macOS shell alias in `~/.zshrc`/`~/.bashrc`
`npm install`	Also runs macOS alias setup via `postinstall`

Local validation

npm run build
npm test

Troubleshooting

`astracode` is not recognized

Run:
```
npm run build
npm run install:global
```
Restart terminal.
Verify:
```
astracode --version
```

`Fatal: cmd.opts is not a function`

This was caused by Commander action argument parsing shape mismatch. Use the current build (v1.1.0+) and relink globally.

`/model` command updates but role routing still looks wrong

Run:

/status

to confirm planner/executor assignment and model values.

Provider picker shows limited/incorrect models

Ensure provider endpoint supports /models.
Run:
```
/provider test <name>
/models
```
If endpoint changed, update URL:
```
/provider set url <name> <url>
```

`pwsh` not found

AstraCode auto-falls back to powershell on Windows for PowerShell commands.

Ctrl+C behavior

By design in v1.1.0, exiting requires 3 Ctrl+C presses to prevent accidental termination.

# Run AstraCode with Ollama and a specific model
astracode chat --ollama qwen3.5:latest

# Run AstraCode with llama.cpp and a specific model
astracode chat --llama qwen2.5-coder-7b-instruct-q4_k_m.gguf

# Run AstraCode with a local AstrAPI endpoint
astracode chat --astrapi http://192.168.1.44:19090/v1

  Use these commands for your client terminal:

   1. Windows CMD set "ASTRAPI_API_KEY=astracode123" && astracode chat --astrapi http://172.18.54.226:19090/v1
   2. Windows PowerShell $env:ASTRAPI_API_KEY="astracode123"; astracode chat --astrapi http://172.18.54.226:19090/v1
   3. Linux/macOS Bash export ASTRAPI_API_KEY=astracode123 && astracode chat --astrapi http://172.18.54.226:19090/v1

Version notes

v1.1.0

Added Ctrl+C exit guard (triple press required to quit).
Unified CLI version display and command version metadata.
Expanded README with full setup, architecture, runtime, model, TUI, and troubleshooting documentation.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
node_runner		node_runner
scripts		scripts
src		src
vscode-extension		vscode-extension
.gitignore		.gitignore
AstraCode_Blackbook_v3.docx.txt		AstraCode_Blackbook_v3.docx.txt
README.md		README.md
add20.py		add20.py
api_tester.ts		api_tester.ts
changes_readme.md		changes_readme.md
data.txt		data.txt
err.txt		err.txt
image.png		image.png
implementation_plan.md.resolved		implementation_plan.md.resolved
openai_api_call.py		openai_api_call.py
openai_models.py		openai_models.py
package-lock.json		package-lock.json
package.json		package.json
print_13.py		print_13.py
task.md		task.md
test.py		test.py
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

AstraCode v1.0.2

Table of contents

What AstraCode does

Core features

Architecture

High-level flow

Roles

Routing modes

Install and setup

Prerequisites

Install from repository

Global command install

Windows alias helper (PowerShell)

macOS alias auto-install

Running AstraCode

Normal chat

Runtime override options

Dev scripts

Configuration reference

Example config

Environment variables

Provider and model management

Recommended free baselines

Command palette model flow

All slash commands

Interactive TUI and keybindings

Main layout

Keybindings

AstrAPI for remote/local GPU serving

Typical second-laptop workflow

llama.cpp thinking / advanced options

Tooling behavior

Registered tools

Shell runner auto-selection on Windows

Output style

Verification and git workflows

Verification controls

Git commands

Developer scripts and testing

package.json scripts

Local validation

Troubleshooting

astracode is not recognized

Fatal: cmd.opts is not a function

/model command updates but role routing still looks wrong

Provider picker shows limited/incorrect models

pwsh not found

Ctrl+C behavior

Version notes

v1.1.0

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`astracode` is not recognized

`Fatal: cmd.opts is not a function`

`/model` command updates but role routing still looks wrong

`pwsh` not found

Packages