Erosolar Coder

1. Installation Guide

Erosolar Coder requires Node.js >= 20.0.0. Install the agent globally using NPM to make the binary available across your system.

2. Authentication (Google SSO)

To ensure secure and robust usage, Erosolar Coder requires an active session authenticated via Google Single Sign-On. When you run the CLI for the first time, it will automatically initiate a secure OAuth flow.

Your browser will open to our dedicated Firebase login page. Upon successful authentication, the terminal will resume and drop you into the interactive shell.

Manual API Key Configuration

If you prefer to inject your own DeepSeek API key, you can do so directly:

3. Usage & Commands

Interactive Shell

The standard way to use the agent is to launch the interactive shell. The shell persists conversation history and allows you to chat, review tool executions, and direct the agent dynamically.

Human-In-The-Loop (HITL) Workflow

Erosolar Coder is designed for maximal human control. It never executes critical commands without your oversight. The standard workflow follows a rigorous cycle:

1. Inquiry: You provide a task or question.
2. Research: The agent explores your codebase and proposes a strategy.
3. Strategy Review: You review the proposed plan. You can approve it, request modifications, or cancel.
4. Execution: Only upon your approval does the agent perform "surgical" edits or execute shell commands.
5. Validation: The agent verifies the changes and presents the results for your final review.

This HITL approach ensures that you remain the ultimate authority, preventing any unintended modifications to your project.

Interactive Slash Commands

Inside the interactive shell, you can control the engine using slash commands:

• /model - Cycle providers, or /model <name> to switch directly.
• /key - Set the DeepSeek API key for this machine.
• /secrets - Show or set all provider keys.
• /auto - Toggle auto-continue (off → on → dual → off).
• /bash <cmd> - Run a one-shot local shell command without leaving the session.
• /stats - Show session token + cost stats.
• /keys - Show the keyboard-shortcuts panel.
• /clear - Clear the terminal screen.
• /help - List all available commands.
• /exit - Quit (Ctrl+C also works).

Pre-filling the first prompt

You can pass a positional prompt on the command line. The CLI still launches in interactive mode — the prompt is queued as your first message, and the session continues from there:

Interactive-only by design

There is no headless, one-shot, or pipe mode. Every session runs through the Ink renderer against a live TTY — if stdin or stdout isn't a terminal, the CLI errors out fast rather than emit unrenderable output into a pipe. The HITL approval gates that make this CLI safe (every diff and shell command pauses for your accept / edit / reject) only function with a real terminal, so we don't ship a non-interactive escape hatch.

4. Advanced Features

Massive 1M Token Context Window

Leverage the full power of the DeepSeek model with a massive context window. The agent can ingest entire repositories, maintaining deep awareness of your project's architecture and inter-dependencies.

Tool-Augmented Intelligence

Erosolar Coder is not just a chatbot. It is equipped with a suite of system tools:

• Filesystem Tools: Surgical reads and writes with conflict detection.
• Shell Execution: Run builds, tests, and linters directly from the agent.
• Search & Discovery: High-performance grep and glob tools for navigating large codebases.

Luxurious Terminal UI

Experience a premium, metallic-themed interface that brings a modern web aesthetic to the terminal. With smooth animations, rich markdown rendering, and intuitive layouts, it's a productivity tool you'll love using.

Flexible Model Support

While optimized for DeepSeek, Erosolar Coder supports switching between various models to suit your specific needs, all manageable via the /model command.

5. ⟡ Human-In-The-Loop Walkthrough

HITL is the core discipline behind Erosolar Coder's accuracy. The agent never edits code, runs commands, or makes irreversible decisions without you reviewing the plan first. Each loop guarantees maximal accuracy by inserting a verification step where models typically guess.

Why HITL = Maximal Accuracy

Most AI agents fail by doing too much, too quickly. They generate, edit, and execute in one motion — and the cost of a single hallucinated edit is paid in real corrupted files or shipped bugs. Erosolar Coder inserts a deliberate review gate after research and before execution. The agent commits to a plan in writing, you scrutinise it, and only an explicit approval lets it touch your codebase.

• No silent edits. Every multi-file change shows you the exact diff first.
• Reversible by default. All write operations have an explicit undo path.
• Confidence calibrated. When the agent is unsure, it asks instead of guessing.
• Audited execution. Each shell command logs its full invocation and exit code.

6. Engineering — how Erosolar works

This is the high-level engineering doc. The authoritative version lives in docs/ENGINEERING.md in the repo and is kept in sync with the architecture as it changes. If a detail here drifts from the code, the file is canonical.

System map

CLI ──Firebase ID token──▶ AWS API Gateway ─▶ AWS Lambda
 │                                              │
 ▼                                              ▼
Firebase Hosting + Auth                    DeepSeek / Stripe / GitHub /
+ Firestore (Spark plan)                   Tavily / Anthropic / Proton SMTP
        

Four boxes, one trust boundary (the Firebase ID token), and one reason this isn't all on Firebase: the original GCP account was suspended and the new one is on the Spark plan, which doesn't run Cloud Functions. Everything stateful that Spark does support (Hosting, Auth, Firestore, FCM) stayed on Firebase. Everything else — Cloud Functions, scheduled jobs, secret storage — moved to AWS.

Trust boundary

Client signs in with Google → Firebase mints an ID token → client sends Authorization: Bearer <jwt> to API Gateway → Lambda's firebase-admin verifies via the public JWKS, populates request.auth.uid, runs the handler. AWS Lambda has no persistent identity for end-users; every request is re-verified against Firebase Auth.

src/core/ agent + auth

• auth.ts — Local HTTP callback server on a free port in 59999–60099, opens https://ero.solar/login?port=<n>, persists tokens to ~/.erosolar/auth.json with mode 0o600. Atomic write (tmp + rename) to avoid concurrent-CLI races.
• secretStore.ts — Local API-key storage (~/.erosolar/secrets.json, mode 0o600) for users who paste their own DeepSeek/Tavily keys. Server-side shared keys live in AWS Secrets Manager.
• hitl.ts — Human-in-the-loop decision system. Single source of truth, emits prompt-open / prompt-close events that the agent run-timeout and the renderer subscribe to. Run-timeout pauses while a HITL prompt is open; renderer suspends its keypress capture so arrows reach the HITL menu only.
• shutdown.ts — Centralised SIGINT / SIGTERM / uncaughtException / exit handlers. The synchronous exit handler emits \x1b[?25h\x1b[?2004l so a crash never leaves the user's shell in bracketed-paste mode with a hidden cursor.

src/runtime/ agent loop

• agentController.ts — Owns the model.send loop, fallback logic on provider failures, run-timeout budget. Listens for HITL events to pause/resume the timer.
• agentSession.ts — Wraps AgentRuntime from src/core/agent.ts. Turns model deltas into a single event stream the UI consumes.

src/ui/ renderer (two paths)

There are two terminal renderers, selected at construction:

• Legacy (UnifiedUIRenderer.ts, ~6.8k LOC) — Direct stdout writes, manual ANSI escapes, in-place overlay rewrites, custom render gate at 30 fps. Default path.
• Ink (src/ui/ink/, ~1.5k LOC) — React reconciler from ink@7. Owns frame coalescing, visual-column counting (CJK / emoji ZWJ), resize handling, ANSI emission. Opt-in via EROSOLAR_INK=1.

Both implement IPromptController; interactiveShell.ts doesn't change between modes. The Ink path migration was incremental (Phases 1–6), each phase shipped with subprocess hardening tests.

src/tools/ agent abilities

File ops (Read, Edit, Write, Glob, Grep), shell execution (Bash), task management, web search. Glob uses an anchored regex with a sentinel pass for ** to prevent the single-* replace from clobbering the .* body — a real pre-existing bug surfaced via test-first hardening.

aws/lambda/src/ backend

• index.js — Lambda entry. Routes API Gateway events by path: /callable/<name>, /api/<name>, EventBridge cron.
• handlers.js — Near-verbatim copy of the original Firebase Functions code. Routed through a shim so the original onCall(...) / onRequest(...) / onSchedule(...) declarations work unchanged.
• shim.js — Re-implements the firebase-functions v1+v2 surface. Each onCall / onRequest / onSchedule returns a descriptor the Lambda router dispatches against.
• secrets.js — Loads provider keys (DeepSeek, Stripe, GitHub App, Tavily, Anthropic, Proton SMTP) plus the Firebase service account JSON from Secrets Manager into process.env on cold start.

Schedules & webhooks

EventBridge cron rules invoke Lambda directly: dailyDeepseekBalanceReport at 15:00 UTC. Stripe webhook + GitHub webhook hit fixed paths under /api/<name>; signature verification (HMAC-SHA256) happens in the handler, never via ===.

Testing discipline

Tests run real, no compromises — same code production loads, no mocked LLMs / fake filesystems / stub renderers when the test claims to verify those. Hardening tests (test/v*-hardening.test.ts) are the canonical proof that fixed issues stay fixed; CI runs them on every PR. The Ink subprocess tests drive real Ink with real stdin pipes through the same dist artifact production runs.

7. Pricing

Erosolar bills only for what the language model actually processes. No subscription, no minimums.

A typical short conversation (~1,000 input + 300 output tokens) costs about $0.0007 at current rates — the guest tier covers roughly 700 turns before exhausting.

Top up any time at /portal. Stripe-issued, instant credit add to your account balance.

Full list price (effective June 1, 2026)

After the launch period the rates roll back to full list, applied automatically by the backend on every request:

• Input: $1.740 / 1M tokens
• Output: $3.480 / 1M tokens

Output is always 2× input — same ratio across both tiers.

8. Contact

Built and maintained by Bo Shang.

• Email: bo@ero.solar
• Support relay: tap Request a human in the Erosolar Helper popup (top nav) — your message is emailed to daburu.dragon@gmail.com via Proton SMTP and replies route to your inbox.