# Erosolar Coder

[![npm version](https://img.shields.io/npm/v/@erosolarcoder/erosolar-coder)](https://www.npmjs.com/package/@erosolarcoder/erosolar-coder)

> **First public research run — 3 hours of unattended offensive
> security research, useful enough to submit to Google Bug Hunters.**
>
> The first prompt I asked
> [erosolar-coder](https://www.npmjs.com/package/@erosolarcoder/erosolar-coder)
> to run autonomously was an automated security-research pass for
> submission to the [Google Bug Hunters](https://bughunters.google.com/)
> program. It ran unattended for **3 continuous hours** on a CLI
> still under initial development and produced useful offensive-
> security research. For a starting CLI that's an amazing accomplishment.
>
> The open-source first-prompt result is at
> [`Aroxora/google-bug-hunters-initial-AI-research-and-offensive-research-results`](https://github.com/Aroxora/google-bug-hunters-initial-AI-research-and-offensive-research-results).
> All subsequent research is in a separate **private** repository
> under responsible-AI and cyber-safety guidelines, by my own AI-safety,
> regulatory, and moral judgement. I'm open-sourcing the first prompt
> that ran — which showed extreme promise — to share the research
> result responsibly with others.

---

Erosolar Coder is an AI-powered CLI agent that uses DeepSeek-V4-Pro to
deliver coding assistance at ~30× the cost-efficiency of comparable
agents. The CLI is the production-blessed surface for coding work.

A web build and a personal-AI ("Jarvis") surface were tried earlier
and have been retired:

- **Web coder** moved to [`erosolar-coder-web`](https://github.com/erolunar/erosolar-coder-web)
  (placeholder). Web-driven coding agents lack the user
  test-and-verify loop a terminal provides — the user can't see every
  diff, every shell command, every test result alongside the agent's
  output and interrupt or course-correct in real time. Without that
  loop, the agent stacks hallucinated assertions and wrong imports
  before anyone can catch them. The CLI is the surface that keeps the
  agent honest.
- **Jarvis** (the personal-AI surface — iOS, Apple Watch, Android,
  web) moved to [`erosolar-jarvis`](https://github.com/erolunar/erosolar-jarvis)
  (placeholder). The personal-assistant role is being deferred to
  [OpenClaw](https://openclaw.ai/), which already does that role
  end-to-end. This repo focuses on what it's actually best at.

This README is the practical entry point. If you're trying to
understand how the system actually works, read
**[`docs/ENGINEERING.md`](docs/ENGINEERING.md)**.

## Install

```bash
npm install -g @erosolarcoder/erosolar-coder
```

Exposes two CLIs: `deepseek`, `erosolar` (synonyms; pick the one you
prefer).

```bash
erosolar                       # interactive shell
erosolar -q "explain X"        # one-shot prompt
git diff | erosolar            # pipe mode
erosolar --key sk-...          # set DeepSeek key
```

In-shell commands: `/model`, `/secrets`, `/help`, `/clear`. See
`/help` for the full list.

## How it works (skim)

```
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 there. Everything else moved
to AWS — Lambda for handlers, Secrets Manager for the 14+ shared
keys, EventBridge for cron schedules, no extra infrastructure.

## Layout

```
src/                       CLI source
  core/                    Auth, secret store, hooks, HITL, agent loop
  runtime/                 Agent controller, session, tool runtime
  tools/                   Read / Edit / Write / Bash / Glob / Grep
  capabilities/            Pluggable capability modules
  ui/                      Renderer (legacy + Ink — see ENGINEERING.md)
  headless/                Interactive shell + CLI bootstrap
  contracts/               Shared schemas (agent, tools, profiles)

aws/                       AWS backend
  lambda/src/              Lambda runtime — handlers, shim, secrets
  iam/                     Trust + inline policies (least-privilege)
  scripts/                 deploy.sh, setup-secrets.sh

site/                      Firebase Hosting (npm landing + Helia
  public/                  marketing + portal + docs)
  functions/               Legacy Firebase Functions source (kept for
                           reference; not deployed under Spark plan)

Erosolar_Browser/          Helia — Electron browser companion

docs/ENGINEERING.md        Authoritative system documentation
aws/MIGRATION.md           Firebase → AWS migration playbook
CLAUDE.md                  Project conventions for agentic contributors
```

## Build / test / deploy

```bash
npm install                                    # deps for CLI
npx tsc -p tsconfig.json                       # build
npm test                                       # full jest suite (~14s)
npx jest --testPathPatterns "v[0-9]+\\.[0-9]+-hardening"  # hardening only

bash aws/scripts/deploy.sh                     # Lambda + API Gateway
cd site && firebase deploy --only hosting --project erosolar-1b0db
```

The hardening test suite (`test/v*-hardening.test.ts`) is the
canonical proof that closed security/correctness issues stay closed;
CI runs it on every PR.

## Cost

Per-million tokens at list rates (May 2026, short-context tier):

| Tool | Model | Input $/M | Output $/M |
| --- | --- | --- | --- |
| **Erosolar Coder** (now) | `deepseek-v4-pro` *75% off through 2026-05-31* | **$0.435** | **$1.74** |
| **Erosolar Coder** (after 2026-05-31) | `deepseek-v4-pro` list | $1.74 | $3.48 |
| Claude Code (Sonnet) | `claude-sonnet-4.6` | $3.00 | $15.00 |
| Claude Code (Opus) | `claude-opus-4.7` | $5.00 | $25.00 |
| OpenAI Codex CLI | `gpt-5.5` | $5.00 | $30.00 |
| OpenAI Codex CLI (Pro) | `gpt-5.5-pro` | $30.00 | $180.00 |
| Cursor agents | `claude-sonnet-4.6` | $3.00 | $15.00 |
| Gemini CLI | `gemini-3.1-pro` | $2.00 | $12.00 |
| Grok CLI | `grok-4.3` | $1.25 | $2.50 |

DeepSeek's 75%-off promotional rate applies until **2026-05-31
15:59 UTC**. After that, the list price ($1.74 / $3.48) takes over
— still well under every Claude / OpenAI / Cursor option, and
within Grok's range. Long-context surcharges (prompts > 200k
tokens): `gpt-5.5` doubles to $10 / $45; `gpt-5.5-pro` doubles to
$60 / $270; `gemini-3.1-pro` goes to $4 / $18. Cache-write /
cache-hit reductions on Claude (`$0.50` / MTok cache hit on Opus
4.7, `$10` / MTok 1h cache write) and on `gpt-5.5` (cached input
$0.50–$1.00 / MTok depending on context tier) further close the
gap on those vendors at the cost of operational complexity.
DeepSeek-V4-Pro has no cache tier — list price is the price.

A representative coding session (~150k input + 30k output, all
short-context) costs:

| Tool | Cost | vs. Erosolar (now) |
| --- | --- | --- |
| **Erosolar Coder** — promo through 2026-05-31 | **~$0.09** | — |
| **Erosolar Coder** — list (post-2026-05-31) | ~$0.37 | 4.0× |
| Grok CLI (`grok-4.3`) | ~$0.26 | 2.9× |
| Gemini CLI (`gemini-3.1-pro`) | ~$0.66 | 7.2× |
| Claude Code (Sonnet 4.6) | ~$0.90 | 9.8× |
| Claude Code (Opus 4.7) | ~$1.50 | 16× |
| OpenAI Codex CLI (`gpt-5.5`) | ~$1.65 | 18× |
| OpenAI Codex CLI (`gpt-5.5-pro`) | ~$9.90 | 108× |

DeepSeek-V4-Pro performs in the same SWE-bench Verified band as
Sonnet 4.6 on most coding benchmarks, so the ~10× cost gap (today)
is real delivered savings, not a quality concession. After the
promotional period the gap narrows to ~2.4× vs. Sonnet — still a
material saving, but Grok 4.3 will be the cheapest cell on the
table at that point and worth a side-by-side eval.

## Authorization scope

Erosolar Coder ships with the rails turned down for security
research, red-team, and infrastructure automation that mainstream
agents refuse to help with — destructive shell commands, sudo,
credential testing, exploit scaffolding. Use it on systems you own
or are explicitly authorized to test. The CLI logs the authorization
scope before running offensive tooling — read it.

## Surfaces

- **Terminal CLI** — `npm install -g @erosolarcoder/erosolar-coder`,
  then `erosolar`. The production surface.
- **Helia** — Electron browser companion under `Erosolar_Browser/`,
  shares the same Firebase auth and balance with the CLI. Landing
  page at <https://ero.solar/helia>.

The two are linked account-wide via Firebase Auth + the
`users/{uid}` Firestore doc; sign in once and your balance and
identity are visible from either.

## Contributing

Read `CLAUDE.md` first — it documents the testing discipline and the
"research before custom code" rules this repo enforces. Every fix
must ship with a test that fails before and passes after.

Test gate is **local, not CI**. Install the pre-push hook once per
checkout — it runs `npm test` before every `git push` so a broken
build never reaches origin:

```bash
git config core.hooksPath scripts/git-hooks
```

Bypass in an emergency with `git push --no-verify`. The previous
`.github/workflows/hardening.yml` workflow was deleted because the
repo is private + solo and GH Actions runs were burning free-tier
minutes + sending failure emails to cover what `npm test` already
covers locally.

## Contact

Bo Shang — building Ero.Solar.

- Email: [bo@ero.solar](mailto:bo@ero.solar)
- Phone: [+1 508-260-0326](tel:+15082600326)
- GitHub: [@Aroxora](https://github.com/Aroxora)
- LinkedIn: [linkedin.com/in/bo-shang-04923b3a6](https://www.linkedin.com/in/bo-shang-04923b3a6/)
- X: [@erolunar](https://x.com/erolunar)
- YouTube: [@erosolarai](https://www.youtube.com/@erosolarai)

## License

MIT