echospace 0.1.0-alpha.5 → 0.1.0-alpha.6

package/README.md

@@ -6,54 +6,45 @@
 
 <p align="center"><strong>The open-source, local-first prompt debugging workspace for LLM developers.</strong></p>
 
-Debug, iterate, and manage your prompts across OpenAI, Anthropic, and Google — all from your terminal. No cloud, no accounts, no lock-in.
+<p align="center">
+  Debug, iterate, and manage your prompts across multiple LLM providers — all from your terminal.<br/>
+  No cloud. No accounts. No lock-in.
+</p>
 
 ---
 
 ## Why EchoSpace?
 
-### Local First
-
-All data stored as `.echo` files on disk. No cloud, no accounts. Your prompts stay on your machine, version-controlled alongside your code.
-
-### Open Source & Customizable
-
-MIT-licensed. Pluggable provider adapters (OpenAI, Anthropic, Google). YAML-based config with `${ENV_VAR}` substitution.
-
-### CLI & SDK
+Prompt engineering is iterative, but most tools make you choose between a polished UI and full control over your data. EchoSpace gives you both: a browser-based workspace that runs entirely on your machine, stores conversations as plain files you can version-control, and works with any OpenAI-compatible provider out of the box.
 
-`npx echospace@alpha` to launch. Core TypeScript modules (`parseEcho`, `serializeEcho`, `smartParse`, provider registry) can be imported as a library for building your own tools.
+- **Local-first** — all data stored as `.echo` files on disk, version-controlled alongside your code
+- **Open source** — MIT-licensed, pluggable provider adapters, `${ENV_VAR}` substitution in config
+- **CLI & library** — `npx echospace@alpha` to launch; core modules (`parseEcho`, `serializeEcho`, `smartParse`, provider registry) are importable as a library
 
 ---
 
 ## Features
 
-- **Multi-provider streaming** — OpenAI, Anthropic, Google Gemini with SSE streaming
-- **Universal `.echo` format** — NDJSON-based, human-readable conversation protocol
-- **Smart Paste** — auto-detects and converts conversations from ChatGPT, Claude, Gemini, or raw text
-- **Timeline / history with branching** — revert to any point in a conversation
-- **Tool use support** — `tool_call` / `tool_result` parts
-- **Token counting** — tiktoken-based token estimation
-- **Image support** — inline images in messages (base64 or URL)
+- **Multi-provider streaming** — SSE streaming across all configured providers (OpenAI, Anthropic, Google, or any OpenAI-compatible gateway)
+- **Universal `.echo` format** — NDJSON-based, human-readable conversation protocol designed for diffing and version control
+- **Smart Paste** — auto-detects and converts conversation exports from major LLM platforms or raw text
+- **Timeline & branching** — revert to any point in a conversation, fork branches, compare results
+- **Tool use support** — first-class `tool_call` / `tool_result` message parts
+- **Token counting** — tiktoken-based token estimation shown in real time
+- **Image support** — inline images in messages via base64 or URL
 - **Per-conversation model settings** — temperature, max_tokens, top_p, response_format, JSON schema, tools
 
 ---
 
-## Quick Start
+## Getting Started
 
-### 1. Install skills
-
-EchoSpace ships with agent skills that work with any coding agent — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenAI Codex](https://openai.com/index/codex/), or any tool that supports the skills/SKILL.md convention.
+### 1. Initialize
 
 ```bash
-npx skills add stonexer/echospace
+npx echospace@alpha init
 ```
 
-### 2. Configure providers
-
-```bash
-npx echospace init
-```
+The interactive setup wizard configures your provider and API key:
 
 ```
 ◆ Which LLM service do you use?
@@ -67,9 +58,14 @@ npx echospace init
 │ sk-xxxxxxxx
 
 ✓ Config saved to ~/.echospace/config.yaml
+
+◆ Install agent skills for your coding agent? (Claude Code, Codex, etc.)
+│ ● Yes / ○ No
+
+✓ Skills installed!
 ```
 
-### 3. Launch
+### 2. Launch
 
 ```bash
 npx echospace@alpha
@@ -78,31 +74,25 @@ npx echospace@alpha
 Or install globally:
 
 ```bash
-pnpm add -g echospace
+pnpm add -g echospace@alpha
 echospace ./my-project
 ```
 
-This will:
+EchoSpace will:
 
 1. Create a `.echo/` workspace in your project directory
 2. Start a local server and open the UI in your browser
 
 ```
-  ╔══════════════════════════════════════╗
-  ║           EchoSpace v0.1.0          ║
-  ╠══════════════════════════════════════╣
-  ║  Workspace: /my-project/.echo        ║
-  ║  URL:       http://localhost:3240    ║
-  ╚══════════════════════════════════════╝
+  ██████████████
+  ██          ██   EchoSpace v0.1.0
+  ██  ██████  ██
+  ██  ██  ██  ██   Workspace  /my-project/.echo
+  ██  ██████  ██   URL        http://localhost:3240
+  ██          ██
+  ██████████████
 ```
 
-### Available Skills
-
-| Skill                     | Description                                                                                    |
-| ------------------------- | ---------------------------------------------------------------------------------------------- |
-| `/echospace-export`       | Convert conversation files (OpenAI, Anthropic, Google, Helicone, raw text) into `.echo` format |
-| `/echospace-integrate`    | Integrate `.echo` export into your own app                                                     |
-
 ### CLI Options
 
 ```
@@ -113,6 +103,26 @@ echospace [workdir] [options]
   --no-open           Don't open browser automatically
 ```
 
+### Agent Skills
+
+| Skill | Description |
+| --- | --- |
+| `/echospace-export` | Convert conversation exports from major LLM platforms into `.echo` format |
+| `/echospace-integrate` | Integrate a `.echo` export into your own app |
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+| --- | --- |
+| Frontend | React 19, Tailwind CSS v4, Zustand, CodeMirror |
+| Backend | Hono, Node.js |
+| Build | Vite, tsup, TypeScript 5 |
+| Testing | Vitest |
+| Tokenization | tiktoken |
+| Package manager | pnpm |
+
 ---
 
 ## The `.echo` Format
@@ -131,7 +141,7 @@ Each message can contain multiple part types: `text`, `thinking`, `tool_call`, `
 
 ## Configuration
 
-On first launch, EchoSpace creates `~/.echospace/config.yaml`. Fill in the `api_key` for the providers you want to use — unconfigured providers are automatically ignored.
+Run `npx echospace@alpha init` to create `~/.echospace/config.yaml`, or edit it manually:
 
 ```yaml
 providers:
@@ -162,9 +172,26 @@ providers:
       - gemini-2.5-pro
       - gemini-2.5-flash
       - gemini-2.0-flash
+
+  - name: vercel-ai-gateway
+    type: openai
+    api_key: xxxxxxxx
+    base_url: https://ai-gateway.vercel.sh/v1
+    models:
+      - anthropic/claude-sonnet-4-6
+      - openai/gpt-4.1
+      - google/gemini-2.5-pro
+
+  # Custom OpenAI-compatible gateway
+  - name: custom
+    type: openai          # or: anthropic, google
+    api_key: xxxxxxxx
+    base_url: https://my-proxy.example.com/v1
+    models:
+      - my-model-name
 ```
 
-> **Tip:** `${ENV_VAR}` syntax is also supported for API keys — they are resolved from your environment at runtime. `.env` files in your project directory are auto-loaded.
+> **Tip:** `${ENV_VAR}` syntax is supported for API keys — values are resolved from your environment at runtime. `.env` files in your project directory are auto-loaded.
 
 ---
 
@@ -182,6 +209,7 @@ pnpm build        # Build for production
 pnpm typecheck    # Type-check without emitting
 pnpm lint         # ESLint
 pnpm format       # Prettier
+pnpm test         # Run tests
 ```
 
 ---

package/dist/cli/index.js

@@ -866,6 +866,7 @@ function startServer(options) {
 
 // src/cli/init.ts
 import * as p from "@clack/prompts";
+import { execSync } from "child_process";
 import { homedir } from "os";
 import path4 from "path";
 var CONFIG_DIR = path4.join(homedir(), ".echospace");
@@ -942,7 +943,7 @@ async function runInit() {
     const baseUrl = await p.text({
       message: "Base URL (e.g. https://my-proxy.example.com/v1):",
       validate: (v) => {
-        if (!v.trim()) return "URL is required";
+        if (!v?.trim()) return "URL is required";
         try {
           new URL(v.trim());
         } catch {
@@ -1006,11 +1007,25 @@ async function runInit() {
   saveConfig(CONFIG_DIR, config);
   const configPath = path4.join(CONFIG_DIR, "config.yaml");
   p.log.success(`Config saved to ${configPath}`);
+  const installSkills = await p.confirm({
+    message: "Install agent skills for Claude Code / Cursor? (npx skills add stonexer/echospace)"
+  });
+  if (installSkills && !isCancel2(installSkills)) {
+    const s = p.spinner();
+    s.start("Installing skills...");
+    try {
+      execSync("npx skills add stonexer/echospace", { stdio: "pipe" });
+      s.stop("Skills installed!");
+    } catch {
+      s.stop("Failed to install skills");
+      p.log.warn("Run manually: npx skills add stonexer/echospace");
+    }
+  }
   p.outro("You're all set! Run `npx echospace@alpha` to start.");
 }
 
 // src/cli/index.ts
-var VERSION = "0.1.0-alpha.5";
+var VERSION = "0.1.0-alpha.6";
 var CONFIG_DIR2 = path5.join(homedir2(), ".echospace");
 function loadEnvFile(dir) {
   const envPath = path5.join(dir, ".env");
@@ -1029,19 +1044,23 @@ function loadEnvFile(dir) {
   }
 }
 var program = new Command();
-program.name("echospace").description("The best open-source local prompt debugging tool").version(VERSION).argument("[workdir]", "Workspace directory", ".").option("-p, --port <port>", "Port to serve on").option("--no-open", "Don't open browser automatically").action(async (workdir, options) => {
-  const baseDir = path5.resolve(process.cwd(), workdir);
-  const workspaceDir = path5.join(baseDir, ".echo");
-  loadEnvFile(baseDir);
-  loadEnvFile(process.cwd());
-  if (!fs3.existsSync(workspaceDir)) {
-    fs3.mkdirSync(workspaceDir, { recursive: true });
-  }
-  fs3.mkdirSync(CONFIG_DIR2, { recursive: true });
-  ensureConfig(CONFIG_DIR2);
-  const port = options.port ? parseInt(options.port, 10) : await getPort({ port: portNumbers(3240, 3249) });
-  const url = `http://localhost:${port}`;
-  console.log(`
+program.name("echospace").description("The best open-source local prompt debugging tool").version(VERSION).argument("[workdir]", "Workspace directory", ".").option("-p, --port <port>", "Port to serve on").option(
+  "-d, --dir <path>",
+  "Open this directory directly as the workspace (skips the .echo subdir)"
+).option("--no-open", "Don't open browser automatically").action(
+  async (workdir, options) => {
+    const baseDir = path5.resolve(process.cwd(), workdir);
+    const workspaceDir = options.dir ? path5.resolve(process.cwd(), options.dir) : path5.join(baseDir, ".echo");
+    loadEnvFile(baseDir);
+    loadEnvFile(process.cwd());
+    if (!fs3.existsSync(workspaceDir)) {
+      fs3.mkdirSync(workspaceDir, { recursive: true });
+    }
+    fs3.mkdirSync(CONFIG_DIR2, { recursive: true });
+    ensureConfig(CONFIG_DIR2);
+    const port = options.port ? parseInt(options.port, 10) : await getPort({ port: portNumbers(3240, 3249) });
+    const url = `http://localhost:${port}`;
+    console.log(`
   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588
   \u2588\u2588          \u2588\u2588   EchoSpace v${VERSION}
   \u2588\u2588  \u2588\u2588\u2588\u2588\u2588\u2588  \u2588\u2588
@@ -1050,17 +1069,18 @@ program.name("echospace").description("The best open-source local prompt debuggi
   \u2588\u2588          \u2588\u2588
   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588
 `);
-  const isDev = process.env.NODE_ENV !== "production" && import.meta.url.includes("/src/");
-  startServer({ port, workspaceDir, configDir: CONFIG_DIR2, dev: isDev });
-  if (options.open) {
-    await open(`http://localhost:${port}`);
+    const isDev = process.env.NODE_ENV !== "production" && import.meta.url.includes("/src/");
+    startServer({ port, workspaceDir, configDir: CONFIG_DIR2, dev: isDev });
+    if (options.open) {
+      await open(`http://localhost:${port}`);
+    }
+    const shutdown = () => {
+      console.log("\nShutting down EchoSpace...");
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
   }
-  const shutdown = () => {
-    console.log("\nShutting down EchoSpace...");
-    process.exit(0);
-  };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-});
+);
 program.command("init").description("Interactive setup for LLM provider configuration").action(runInit);
 program.parse();