codeshark-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeShark contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# CodeShark 🦈
+
+An open-source **terminal coding agent** with a pixel-shark mascot — five
+frontier models (GPT-5.6 Sol, DeepSeek-V4 Flash, GLM 5.3 Flash Thinking,
+Kimi-K3, Gemini 3.6 Flash) behind one OpenAI-compatible endpoint.
+
+Run `codeshark banner --plain` to see the live mascot in your terminal: a dark
+grey head with black eyes, white teeth, and a red mouth.
+
+## How it works
+
+Everything routes through **UnoRouter** (`https://api.unorouter.com/v1`), one
+OpenAI-compatible endpoint. CodeShark ships with a zero-setup **community
+gateway**, so you can start without configuring anything; bring your own
+UnoRouter key whenever you want your own rate limits and private prompts.
+
+The gateway strictly serves only UnoRouter's `:free` lane identifiers — any
+other identifier is refused, so there is no paid path through the gateway.
+
+## Quick start
+
+CodeShark is intentionally **project-folder-only**. You must select the folder
+that the agent is allowed to work in with `--folder` (or `--cwd`). It refuses to
+start chat, setup, model switching, key management, or a prompt without a real
+project folder.
+
+```bash
+# From a cloned checkout:
+npm install
+npm run build
+npm install -g .
+
+# Start CodeShark in the project folder:
+codeshark --folder .
+codeshark --folder . "explain this project"
+
+# Or select another folder from anywhere:
+codeshark --folder path/to/your-project
+codeshark --cwd path/to/your-project "fix the tests"
+
+# After the package is published:
+npx codeshark-cli       # run from any folder without a global install
+npm install -g codeshark-cli
+```
+
+Out of the box, CodeShark talks to the community gateway (which routes through
+UnoRouter), so there is **nothing to configure**. If you installed from a
+checkout and `codeshark` is not recognized yet, use `node dist/index.js
+--folder .` or run `npm install -g .`. All file edits, searches, and commands
+stay inside the selected project folder.
+
+By using CodeShark you agree to the [Terms of Service](TERMS.md) — the first
+interactive start asks you to accept them once, and `codeshark terms` prints
+them anytime.
+
+### Setup: shared gateway or your own key?
+
+On first launch the CLI asks how you want to connect — and you can re-run it
+anytime with `codeshark setup`:
+
+- **My own API key (recommended)** — typed into the terminal **hidden (never
+  echoed)**, stored only on your computer in a locked config file (`0600`
+  permissions), and never printed by CodeShark. Your own key means your own
+  rate limits and private prompts. One UnoRouter key unlocks all 5 models.
+- **Shared gateway** — no key on your computer at all; the gateway's keys live
+  as server-side secrets. Shared free lanes are rate-limited, so the gateway
+  **queues** bursts (you wait a moment instead of erroring) and fails over
+  between UnoRouter → OpenRouter → NVIDIA automatically.
+- **Local Ollama** — fully offline on your own machine.
+
+Your local keys are protected further by the password-locked key vault
+(`codeshark keys`) — scrypt-hashed password, session + CSRF tokens, and keys
+never appear in the page's HTML or the terminal.
+
+## Usage
+
+```
+codeshark --folder .                  interactive chat for this folder
+codeshark --folder . "fix the tests"  one-shot prompt for this folder
+codeshark banner                      just the mascot (no folder needed)
+codeshark --folder . setup            providers / keys wizard
+codeshark --folder . model            list the catalog and active model
+codeshark --folder . keys             open the local key vault
+```
+
+REPL commands: `/help` `/model` `/keys` `/key-status` `/setup` `/clear` `/quit`
+(Ctrl+C also quits). Read the terms anytime with `codeshark terms`. The `/keys` page listens only on `127.0.0.1`, requires a
+local password, and keeps key values hidden in password-style fields; the
+terminal status command only shows masked values.
+
+## Tools the agent can use
+
+- `read_file` / `write_file` / `edit_file` (strict: `oldString` must match **exactly once** or the edit is rejected)
+- `list_directory` / `glob` (`**`, `*`, `?`, `{a,b}`)
+- `code_search` (ripgrep when installed, dependency-free fallback otherwise)
+- `run_command` (bash / cmd, 30s timeout, output capped) — with a built-in
+  danger blocklist: `rm -rf`, `git push`, `sudo`, `curl | sh`, … are refused
+  unless you set `CODESHARK_ALLOW_DANGEROUS=1`
+- `finish` — the model signals completion with a summary
+
+## Providers & models
+
+Everything runs through **UnoRouter** (`https://api.unorouter.com/v1`), one
+OpenAI-compatible endpoint that routes to 45+ upstream providers — all five
+catalog models are served on its `:free` lanes. Switch anytime with
+`/model <name>` in the REPL (or `codeshark model <name>`).
+
+| Model | API identifier | Context | |
+| --- | --- | --- | --- |
+| Chat-GPT 5.6 Sol | `gpt-5.6-sol:free` | 400K | |
+| DeepSeek-V4 Flash | `deepseek-v4-flash-0731:free` | 256K | |
+| GLM 5.3 Flash Thinking | `glm-5.3-flash-thinking:free` | 1M | default |
+| Kimi-K3 | `kimi-k3:free` | 256K | |
+| Gemini 3.6 Flash | `gemini-3.6-flash:free` | 1M | |
+
+\* All models run through the zero-setup gateway without any key — nothing to
+configure.
+
+**Keys:**
+- UnoRouter → https://unorouter.com/en/tokens (one key, 200+ models — the only key you really need)
+- Google AI Studio → https://aistudio.google.com/apikey (`AIza…`)
+
+Run `codeshark setup` to paste a key and pick a default model — it tests the key
+live before saving.
+
+**Rate limits:** shared lanes throttle (~20 req/min, ~200/day). If you hit
+a 429, the agent tells you — wait a moment or switch models with `/model`.
+
+## Configuration
+
+`~/.codeshark.json` (env vars override):
+
+```json
+{
+  "provider": "unorouter",
+  "model": "unorouter/glm-5.3-flash-thinking",
+  "unorouterApiKey": "ur-…",
+  "openrouterApiKey": "sk-…",
+  "nvidiaApiKey": "nvapi-…",
+  "geminiApiKey": "AIza…",
+  "gatewayUrl": "https://your-gateway.workers.dev",
+  "ollamaBaseUrl": "http://127.0.0.1:11434/v1",
+  "ollamaModel": "qwen3-coder:30b",
+  "maxIterations": 25
+}
+```
+
+Env vars: `CODESHARK_MODEL`, `UNOROUTER_API_KEY`, `OPENROUTER_API_KEY`,
+`GEMINI_API_KEY`, `CODESHARK_GATEWAY_URL`, `CODESHARK_GATEWAY_KEY`,
+`CODESHARK_NO_COLOR`, `CODESHARK_NO_BANNER`, `CODESHARK_NO_LOADING`,
+`CODESHARK_ALLOW_DANGEROUS`.
+
+## Run your own community gateway
+
+Anyone can fork the repo and deploy their own gateway — the URL is configurable,
+so your users hit *your* gateway:
+
+```bash
+cd worker
+npx wrangler secret put UNOROUTER_API_KEY    # your UnoRouter key (primary), stays server-side
+npx wrangler secret put OPENROUTER_API_KEY   # optional: OpenRouter fallback key
+npx wrangler secret put NVIDIA_API_KEY       # optional: NVIDIA NIM fallback key (nvapi-…)
+npx wrangler deploy
+```
+
+Then point CodeShark at it:
+
+```bash
+codeshark setup   # or edit ~/.codeshark.json: "gatewayUrl": "https://<you>.workers.dev"
+```
+
+The gateway serves only `:free` model identifiers — it never routes anything
+paid — rate-limits per IP, adds CORS, and refuses any non-`:free` identifier.
+When a provider rate-limits (429), the gateway **waits and retries**, then
+hands off to the next configured provider (UnoRouter → OpenRouter → NVIDIA),
+and per-IP bursts **queue** (wait for a slot) instead of failing. Your keys are
+Worker secrets: never logged, never returned, never visible to users. Clients
+also retry 429s with backoff, so shared lanes feel smooth.
+
+## Architecture
+
+```
+┌────────────┐   messages/tools   ┌──────────────────┐   OpenAI-compatible   ┌──────────────┐
+│  terminal  │ ─────────────────▶ │   agent loop      │ ───────────────────▶ │  provider    │
+│ (repl/cli) │ ◀───────────────── │ (tools, guard)    │ ◀─────────────────── │  chain       │
+└────────────┘   streamed text    └──────────────────┘   SSE stream          └──────┬───────┘
+                                                                                    │
+                                  gateway (Cloudflare Worker, :free only) ◀─────────┤
+                                  unorouter (:free, your key) ◀────────────────────┤
+                                  gemini ◀──────────────────────────────────────────┤
+                                  ollama (local) ◀──────────────────────────────────┘
+```
+
+- `src/provider/` — canonical `ChatClient` interface + adapters (OpenAI-compatible
+  shared core, UnoRouter, OpenRouter, NVIDIA NIM, Gemini conversion, Ollama)
+- `src/agent.ts` — the loop: model → tool calls → results → repeat (25-iteration guard)
+- `src/tools/` — file, search, and shell tools (zero dependencies)
+- `src/banner.ts` — the mascot, defined as a character grid
+- `worker/` — the Cloudflare Worker gateway
+
+## Share it with other computers
+
+Other people run your CodeShark the exact same way you do — through npm.
+Publish once, and anyone with Node.js 18+ can run it from any computer.
+
+The package name is `codeshark-cli` (npm's anti-squatting rules reserve the
+bare `codeshark` name, which is too similar to the existing `code-shark`
+package). The command you type stays `codeshark`:
+
+```bash
+npm login                     # once per computer (create an npm account first)
+npm run typecheck && npm test
+npm pack --dry-run            # preview exactly what ships: dist/, README, LICENSE
+npm publish --access public   # publish version 0.1.0
+```
+
+Bump the version for every release: `npm version patch` (or `minor`/`major`),
+then `npm publish` again.
+
+From that moment, on **any computer** with Node.js 18+:
+
+```bash
+npx codeshark-cli --folder .  # run instantly — no install needed
+npm install -g codeshark-cli  # or install it like a real CLI
+codeshark --folder .          # then use it anywhere
+```
+
+The person on the other computer needs no API key and no account — the model
+provider stays server-side, so it works out of the box. The agent only works
+inside the folder they open with `--folder`; it edits, searches, and runs
+commands there and nowhere else.
+
+Not ready to publish? `npm pack` produces a single `codeshark-<version>.tgz`
+file — send that one file and the receiver runs `npm install -g
+./codeshark-0.1.0.tgz`.
+
+## Development
+
+```bash
+npm install
+npm run typecheck     # tsc --noEmit
+npm test              # build + node:test (agent loop, tools, parsers, banner)
+npm run worker:build  # typecheck the gateway worker
+```
+
+## Roadmap
+
+- [x] Mascot banner, REPL, one-shot mode, setup wizard
+- [x] UnoRouter provider: 5 frontier models, one key
+- [x] Agent loop with streaming + tool calling (UnoRouter/Gemini/Ollama/gateway)
+- [x] File, search, and shell tools with safety blocklist
+- [x] Cloudflare Worker gateway (`:free`-only, UnoRouter-routed)
+- [ ] Session memory / project context
+- [x] npm package metadata and `npx codeshark-cli`/global-install support (publish manually)
+- [ ] Approval prompts for sensitive commands
+- [ ] More providers (Groq, Cerebras, …)
+
+## License
+
+MIT. 🦈

package/TERMS.md

@@ -0,0 +1,72 @@
+# CodeShark Terms of Service
+
+*Last updated: September 4, 2026*
+
+By installing, downloading, or using CodeShark (the "Software"), you agree to
+these Terms of Service. If you do not agree, do not use the Software.
+
+## 1. What CodeShark is
+
+CodeShark is an open-source terminal coding agent. It can read, create, and
+edit files, run searches, and execute commands **inside the project folder you
+explicitly open with `--folder`**. It is a tool you operate — you are
+responsible for choosing when and how it acts.
+
+## 2. No warranty
+
+The Software and the shared gateway service are provided **"AS IS" and "AS
+AVAILABLE"**, without warranty of any kind, express or implied, including
+merchantability, fitness for a particular purpose, and non-infringement. Model
+responses may be incorrect, incomplete, or harmful; verify all output before
+relying on it. The shared gateway is a free, best-effort service — uptime,
+speed, and model availability are not guaranteed.
+
+## 3. Fair use of the shared gateway
+
+When you use the shared gateway (the default "zero setup" path), requests are
+routed through shared free-tier provider lanes. You agree to:
+
+- **Not** resell, redistribute, or grant access to the gateway to third parties.
+- **Not** scrape, stress-test, or otherwise abuse the gateway or its providers.
+- **Not** use the Software for unlawful purposes, spam, or generating harmful
+  content.
+- Accept that rate limits and queues apply to keep the service usable by
+  everyone. Requests may be delayed, queued, or refused to protect the shared
+  free tier.
+
+## 4. Your content
+
+You retain all rights to the prompts you enter and the files you edit. You are
+solely responsible for them. Do not paste passwords, API keys, or other secrets
+into prompts — they may pass through third-party providers. Prompts and
+generated content are not private; treat them accordingly.
+
+## 5. Limitation of liability
+
+To the maximum extent permitted by law, the authors and maintainers of
+CodeShark are **not liable** for any damages arising from use of the Software,
+including lost data, lost profits, corrupted files, or harm caused by generated
+content or executed commands. You use the Software entirely at your own risk.
+
+## 6. API keys
+
+If you paste your own provider key, it is stored locally on your computer in a
+locked configuration file and is never printed by CodeShark. Keys configured on
+the shared gateway are stored as server-side secrets and are never exposed,
+logged, or returned to clients. You are responsible for protecting your own
+keys.
+
+## 7. Changes
+
+These Terms may be updated at any time. Continued use of the Software after
+changes constitutes acceptance of the revised Terms.
+
+## 8. Termination
+
+We may refuse or terminate access to the shared gateway at any time, with or
+without notice, for any reason — including violation of these Terms. The
+open-source Software itself remains available under its MIT license.
+
+## 9. Contact
+
+For questions about these Terms, open an issue in the CodeShark repository.

package/dist/agent.js

@@ -0,0 +1,77 @@
+import { errorMessage } from "./provider/types.js";
+import { defaultSystemPrompt } from "./system.js";
+import { DEFAULT_MAX_ITERATIONS } from "./config.js";
+/**
+ * Run the agent loop for one user prompt:
+ * model → tool calls → execute → feed results back → … until the model
+ * answers (or calls finish) without further tool calls.
+ */
+export async function runAgent(input, opts, events) {
+    const maxIterations = opts.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const messages = opts.initialMessages ? [...opts.initialMessages] : [];
+    const systemPrompt = opts.systemPrompt ?? defaultSystemPrompt(opts.cwd);
+    if (!messages.some((message) => message.role === "system")) {
+        messages.unshift({ role: "system", content: systemPrompt });
+    }
+    messages.push({ role: "user", content: input });
+    const ctx = { cwd: opts.cwd, log: opts.debug };
+    let lastError = null;
+    for (let i = 0; i < maxIterations; i++) {
+        let assistant = null;
+        let streamedText = "";
+        for (const client of opts.clients) {
+            let clientStreamedText = "";
+            const clientEvents = events
+                ? {
+                    onText: (delta) => {
+                        clientStreamedText += delta;
+                        events.onText?.(delta);
+                    },
+                    onToolCall: events.onToolCall,
+                    onDebug: events.onDebug,
+                }
+                : undefined;
+            try {
+                assistant = await client.chat(messages, opts.registry.schemas(), clientEvents);
+                streamedText = clientStreamedText;
+                break;
+            }
+            catch (e) {
+                lastError = e instanceof Error ? e : new Error(String(e));
+                opts.debug?.(`[provider] ${client.provider} failed: ${lastError.message}`);
+            }
+        }
+        if (!assistant) {
+            throw lastError ?? new Error("No provider available.");
+        }
+        const assistantMsg = assistant;
+        messages.push(assistantMsg);
+        const calls = assistantMsg.toolCalls ?? [];
+        if (!calls.length) {
+            return {
+                text: assistantMsg.content,
+                iterations: i + 1,
+                streamedText: streamedText || undefined,
+                history: messages,
+            };
+        }
+        for (const call of calls) {
+            if (call.name === "finish") {
+                const summary = typeof call.args.summary === "string" && call.args.summary.trim() ? call.args.summary.trim() : "Task complete.";
+                return { text: summary, iterations: i + 1, history: messages };
+            }
+            opts.debug?.(`[tool] ${call.name}`);
+            events?.onToolCall?.(call);
+            const result = await opts.registry.execute(call.name, call.args, ctx);
+            messages.push({
+                role: "tool",
+                content: result.content,
+                toolCallId: call.id,
+                toolName: call.name,
+                isError: result.isError,
+            });
+        }
+    }
+    throw new Error(`Agent exceeded ${maxIterations} iterations without finishing. The model may be looping on tool calls — try rephrasing, or set a higher maxIterations in ~/.codeshark.json.`);
+}
+export { errorMessage };

package/dist/ansi.js

@@ -0,0 +1,52 @@
+/**
+ * Minimal ANSI escape-code helpers — zero dependencies.
+ */
+export const ESC = "\u001b[";
+export const RESET = `${ESC}0m`;
+/** True when the current terminal is likely to support color. */
+export function supportsColor() {
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.CODESHARK_NO_COLOR !== undefined)
+        return false;
+    if (process.env.TERM === "dumb")
+        return false;
+    if (process.platform === "win32" && !process.env.TERM)
+        return false;
+    return true;
+}
+/** Style `text` with a foreground RGB color: hex("#d96b43", "x"). */
+export function hex(hexColor, text) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hexColor.trim());
+    if (!m)
+        throw new Error(`Invalid hex color: ${hexColor}`);
+    const n = parseInt(m[1], 16);
+    const r = (n >> 16) & 0xff;
+    const g = (n >> 8) & 0xff;
+    const b = n & 0xff;
+    return `${ESC}38;2;${r};${g};${b}m${text}${RESET}`;
+}
+/** Style `text` with a background RGB color. */
+export function hexBg(hexColor, text) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hexColor.trim());
+    if (!m)
+        throw new Error(`Invalid hex color: ${hexColor}`);
+    const n = parseInt(m[1], 16);
+    const r = (n >> 16) & 0xff;
+    const g = (n >> 8) & 0xff;
+    const b = n & 0xff;
+    return `${ESC}48;2;${r};${g};${b}m${text}${RESET}`;
+}
+export function bold(text) {
+    return `${ESC}1m${text}${RESET}`;
+}
+export function dim(text) {
+    return `${ESC}2m${text}${RESET}`;
+}
+export function underline(text) {
+    return `${ESC}4m${text}${RESET}`;
+}
+/** Remove ANSI escape sequences (useful for tests / piping). */
+export function stripAnsi(text) {
+    return text.replace(/\u001b\[[0-9;]*m/g, "");
+}

package/dist/banner.js

@@ -0,0 +1,94 @@
+import { hex, bold, dim, stripAnsi } from "./ansi.js";
+import { modelLabel, loadConfig, activeModelId } from "./config.js";
+import { findModel } from "./models.js";
+/**
+ * A front-facing pixel shark head, reproduced from the 16×16 mascot artwork:
+ * a rounded dome, two eyes, and one open mouth with pointy zigzag teeth —
+ * white triangular points separated by red gaps, over a white lower jaw.
+ * There is no badge background; the sprite floats directly on the terminal's
+ * own background.
+ */
+const SPRITE_WIDTH = 16;
+function spriteRow(value) {
+    if (value.length !== SPRITE_WIDTH) {
+        throw new Error(`Mascot row is ${value.length} cells; expected ${SPRITE_WIDTH}`);
+    }
+    return value;
+}
+/**
+ * Character grid:
+ *   '.' transparent (terminal background)
+ *   'D' head
+ *   'E' eye
+ *   'W' teeth
+ *   'R' mouth interior
+ */
+export const SPRITE = [
+    spriteRow(".......D........"),
+    spriteRow("......DDDD......"),
+    spriteRow("....DDDDDDDD...."),
+    spriteRow("...DDDDDDDDDD..."),
+    spriteRow("...DDDDDDDDDD..."),
+    spriteRow("..DDDDDDDDDDDD.."),
+    spriteRow(".DDDDDDDDDDDDDD."),
+    spriteRow(".DDEDDWWWWDDEDD."),
+    spriteRow(".DDWDWWWWWWDWDD."),
+    spriteRow(".DWWDWRRRRWDWWD."),
+    spriteRow("DDWDWRRRRRRWDWDD"),
+    spriteRow("DDWDRRRRRRRRDWDD"),
+    spriteRow("DDWWWRWRWRWWWWDD"),
+    spriteRow("DDWWWRWWRWWRWWDD"),
+    spriteRow("DDWWWWWWWWWWWWDD"),
+    spriteRow("DDWWWWWWWWWWWWDD"),
+];
+const COLORS = {
+    D: { fg: "#4a5a68" },
+    E: { fg: "#0b1220" },
+    W: { fg: "#f8fafc" },
+    R: { fg: "#e5484d" },
+};
+function renderSpriteCell(ch, plain) {
+    if (ch === ".")
+        return "  ";
+    if (plain) {
+        if (ch === "E")
+            return "● ";
+        if (ch === "W")
+            return "░░";
+        if (ch === "R")
+            return "▒▒";
+        return "██";
+    }
+    return hex(COLORS[ch]?.fg ?? "#4a5a68", "██");
+}
+export function renderBanner(opts = {}) {
+    const plain = opts.plain ?? false;
+    const cfg = loadConfig();
+    const entry = findModel(activeModelId(cfg));
+    const baseLabel = modelLabel(cfg);
+    const modelLine = opts.modelLine ?? (entry ? `${baseLabel} · ${entry.context} context` : baseLabel);
+    const cwd = opts.cwd ?? process.cwd();
+    const title = plain ? "CodeShark" : bold("CodeShark");
+    const sub = plain ? modelLine : hex("#8ba3ba", modelLine);
+    const dir = plain ? cwd : dim(cwd);
+    const lines = [];
+    const textLines = [title, sub, dir];
+    for (let i = 0; i < SPRITE.length; i++) {
+        let line = "  ";
+        for (const ch of SPRITE[i])
+            line += renderSpriteCell(ch, plain);
+        const text = textLines[i];
+        if (text !== undefined)
+            line += "   " + text;
+        lines.push(line);
+    }
+    if (opts.footer)
+        lines.push("", opts.footer);
+    return lines.join("\n") + "\n";
+}
+export function printBanner(opts = {}) {
+    process.stdout.write(renderBanner(opts));
+}
+export function bannerHasTitle(text) {
+    return stripAnsi(text).includes("CodeShark");
+}