assurgent 0.1.0 → 0.2.1

package/README.md

@@ -1,14 +1,22 @@
-# assurgent Chat Wrapper
+# assurgent
 
-A lightweight wrapper that connects chat (e.g. **Telegram**) to Agent (e.g. **Claude Code CLI**), so you can talk to Claude from your phone — with your entire assurgent workspace as context.
+A lightweight bridge between any **chat platform** and any **coding agent** — talk to your AI coding agent from anywhere.
 
-> Experimental project, early alpha. Expect bugs and breaking changes, use at your own risk.
+> **Warning:** This project is under active development. APIs may introduce breaking changes at any time. Use at your own risk.
+
+> The name *assurgent* carries two meanings: a botanical term for a branch that grows upward (like this project, still growing), and a nod to *agent* hiding in plain sight — **assur·gent**.
 
 ```
-You (Telegram) --> Wrapper --> Claude Code CLI --> Response --> You (Telegram)
+You (Chat) → assurgent → Coding Agent → Response → You (Chat)
 ```
 
-It is not an agent itself. It's a bridge between Telegram and the Claude Code CLI, with automatic session management.
+Not an agent itself. A thin bridge with automatic session management, pluggable on both sides.
+
+### Currently Supported
+
+| Chat Platform | Coding Agent |
+|---|---|
+| Telegram | Claude Code CLI |
 
 ## Quick Start
 
@@ -16,22 +24,15 @@ It is not an agent itself. It's a bridge between Telegram and the Claude Code CL
 
 - [Bun](https://bun.sh) runtime
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
-- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
+- A Telegram bot token from [@BotFather](https://t.me/BotFather)
 
-### Install
+### Install & Configure
 
 ```bash
-cd app
-bun install
+bunx assurgent init
 ```
 
-### Configure
-
-```bash
-cp config.example.json config.json
-```
-
-Edit `config.json`:
+This creates `~/.assurgent/config.json` from the bundled template. Edit it:
 
 ```json
 {
@@ -39,11 +40,7 @@ Edit `config.json`:
     "adapter": "telegram",
     "telegram": {
       "botToken": "YOUR_BOT_TOKEN_HERE",
-      "allowedUserIds": ["YOUR_TELEGRAM_USER_ID"],
-      "placeholder": {
-        "enabled": true,
-        "text": "thinking..."
-      }
+      "allowedUserIds": ["YOUR_TELEGRAM_USER_ID"]
     }
   },
   "agent": {
@@ -51,125 +48,108 @@ Edit `config.json`:
     "claude-code": {
       "model": "sonnet",
       "maxTurns": 10,
-      "flags": ["--dangerously-skip-permissions"],
-      "claudePath": "claude"
+      "flags": ["--dangerously-skip-permissions"]
     }
   },
   "session": {
     "turnLimit": 20
   },
-  "workspacePath": "/path/to/assurgent"
+  "workspacePath": "/path/to/your/workspace"
 }
 ```
 
 To find your Telegram user ID, message [@userinfobot](https://t.me/userinfobot).
 
-> **Note:** If `claude` is not in your shell's PATH (common on servers where PATH is set in `.bashrc`), set `claudePath` to the full path, e.g. `/home/user/.local/bin/claude`.
+> If `claude` is not in your PATH (common on servers), set `claudePath` to the full path, e.g. `/home/user/.local/bin/claude`.
 
 ### Run
 
 ```bash
-bun run dev
+bunx assurgent
 ```
 
 Then message your bot on Telegram.
 
+### Custom Config Location
+
+Set `ASSURGENT_HOME` to use a different config directory:
+
+```bash
+ASSURGENT_HOME=/custom/path bunx assurgent
+```
+
+Default: `~/.assurgent/`
+
 ## Bot Commands
 
-| Command                                 | Description                                    |
-| --------------------------------------- | ---------------------------------------------- |
-| `/new`                                  | Archive current session, start fresh           |
-| `/extend [N]`                           | Extend session by N turns (default: turnLimit) |
-| `/model [opus\|sonnet\|haiku\|default]` | Show or change model for current session       |
-| `/session list`                         | List all sessions with turn usage              |
-| `/session info`                         | Show current session details                   |
-| `/session resume <name>`                | Resume a session by name                       |
-| `/session rename <name>`                | Rename current session                         |
-| `/help`                                 | Show all commands                              |
+| Command | Description |
+|---|---|
+| `/new` | Archive current session, start fresh |
+| `/extend [N]` | Extend session by N turns (default: turnLimit) |
+| `/model [opus\|sonnet\|haiku\|default]` | Show or change model for current session |
+| `/session list` | List all sessions with turn usage |
+| `/session info` | Show current session details |
+| `/session resume <name>` | Resume a session by name |
+| `/session rename <name>` | Rename current session |
+| `/help` | Show all commands |
 
-Any other text message is forwarded to Claude Code in the current session.
+Any other text is forwarded to the coding agent in the current session.
 
 ## Sessions
 
-Sessions always resume the active session until you explicitly start a new one with `/new`.
+Sessions resume automatically until you start a new one with `/new`.
 
-When the turn count reaches the configured `turnLimit` (default: 20), the bot pauses and asks you to decide:
-- `/extend 20` to add more turns and keep the same session
-- `/new` to archive and start fresh
+When turns reach the configured `turnLimit`, the bot pauses and asks you to `/extend` or `/new`.
 
-Session names are auto-generated from the date and first message (e.g. `2026-03-27-fix-bug`).
+Session names are auto-generated from the date and first message (e.g. `2026-03-27-fix-bug`). Override the model per-session with `/model opus` — persists until reset or new session.
 
-You can override the model per-session with `/model sonnet` — this persists until you reset with `/model default` or start a new session.
-
-Sessions persist across restarts via `state/sessions.json` (relative to `workspacePath`).
+Sessions persist across restarts in `~/.assurgent/state/sessions.json`.
 
 ## Config Reference
 
-| Field                               | Description                                                 |
-| ----------------------------------- | ----------------------------------------------------------- |
-| `chat.adapter`                      | Chat platform (`"telegram"`)                                |
-| `chat.telegram.botToken`            | Telegram bot token                                          |
-| `chat.telegram.allowedUserIds`      | Array of allowed Telegram user IDs                          |
-| `chat.telegram.placeholder.enabled` | Show a placeholder message while agent thinks               |
-| `chat.telegram.placeholder.text`    | Placeholder text                                            |
-| `agent.adapter`                     | Agent CLI (`"claude-code"`)                                 |
-| `agent.claude-code.model`           | Default model (e.g. `"opus"`, `"sonnet"`)                   |
-| `agent.claude-code.maxTurns`        | Max agent turns per invocation                              |
-| `agent.claude-code.flags`           | Extra CLI flags (e.g. `["--dangerously-skip-permissions"]`) |
-| `agent.claude-code.claudePath`      | Path to `claude` binary (default: `"claude"`)               |
-| `session.turnLimit`                 | Pause session after N turns, ask user to /extend or /new    |
-| `workspacePath`                     | Absolute path to the assurgent repo root                     |
-
-## Environment Variables Passed to Agent
-
-The wrapper sets these env vars on every Claude Code invocation:
-
-| Variable           | Description                                          |
-| ------------------ | ---------------------------------------------------- |
-| `AGENT_SESSION_ID` | The Claude Code session UUID for the current session |
+| Field | Description |
+|---|---|
+| `chat.adapter` | Chat platform (`"telegram"`) |
+| `chat.telegram.botToken` | Telegram bot token |
+| `chat.telegram.allowedUserIds` | Array of allowed Telegram user IDs |
+| `chat.telegram.placeholder.enabled` | Show placeholder while agent thinks |
+| `chat.telegram.placeholder.text` | Placeholder text (default: `"thinking..."`) |
+| `agent.adapter` | Agent backend (`"claude-code"`) |
+| `agent.claude-code.model` | Default model (`"opus"`, `"sonnet"`, `"haiku"`) |
+| `agent.claude-code.maxTurns` | Max agent turns per invocation |
+| `agent.claude-code.flags` | Extra CLI flags |
+| `agent.claude-code.claudePath` | Path to `claude` binary (default: `"claude"`) |
+| `session.turnLimit` | Pause after N turns, ask to extend or start new |
+| `workspacePath` | Absolute path to workspace for Claude Code |
 
 ## Development
 
 ```bash
-bun install            # Install dependencies
-bun run dev            # Run the wrapper
-bun run typecheck      # Type check (tsc --noEmit)
+git clone https://github.com/thaitype/assurgent.git
+cd assurgent
+bun install
+```
+
+```bash
+bun run dev            # Start with --watch
+bun run typecheck      # tsc --noEmit
 bun test               # Run tests
-bun run lint           # Lint (biome)
-bun run lint:fix       # Auto-fix lint issues
+bun run lint           # Biome check
+bun run lint:fix       # Auto-fix
 ```
 
-## Architecture
+For local development, config is read from `~/.assurgent/config.json` (same as production). Use `ASSURGENT_HOME` to point to a dev-specific config.
+
+### Architecture
 
 ```
-ChatAdapter (Telegram) --> Wrapper Core --> AgentAdapter (Claude Code CLI)
-                              |
-                        Session Manager
-                       (name <-> UUID)
+ChatAdapter (e.g. Telegram) → Wrapper Core → AgentAdapter (e.g. Claude Code CLI)
+                                    │
+                              Session Manager
 ```
 
-Both the chat side and agent side are pluggable interfaces. The design supports adding other chat platforms or agent backends later without touching the core.
+Both sides are pluggable interfaces. Adding a new chat platform or coding agent is just implementing an adapter — no changes to the core.
 
-### Directory Structure
+## License
 
-```
-app/
-├── src/
-│   ├── index.ts             # Entry point
-│   ├── config.ts            # Config loader + validation
-│   ├── core/
-│   │   ├── wrapper.ts       # Core orchestrator
-│   │   └── session-manager.ts
-│   ├── interfaces/
-│   │   ├── chat-adapter.ts
-│   │   └── agent-adapter.ts
-│   ├── chat/
-│   │   └── telegram.ts      # Telegram adapter (grammy)
-│   └── agent/
-│       └── claude-code.ts   # Claude Code adapter (execa)
-├── config.json              # Runtime config (gitignored)
-├── config.example.json      # Committed template
-├── package.json
-├── tsconfig.json
-└── biome.json
-```
+MIT

package/cli.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 // Entry point for `bunx assurgent`
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 const args = process.argv.slice(2);
 
@@ -11,15 +11,16 @@ if (args.includes("--help") || args.includes("-h")) {
 assurgent - Telegram bot bridge to Claude Code CLI
 
 Usage:
-  assurgent [options]
-
-Options:
-  --help, -h       Show this help message
-  --version, -v    Print the version number
+  assurgent          Start the bot
+  assurgent init     Scaffold config.json into ASSURGENT_HOME
+  assurgent --help   Show this help message
+  assurgent --version  Print the version number
 
 Configuration:
-  Requires config.json and .env in the working directory.
-  See config.example.json for the expected structure.
+  Config is loaded from $ASSURGENT_HOME/config.json.
+  ASSURGENT_HOME defaults to ~/.assurgent/ if not set.
+
+  Run "assurgent init" to create the config file, then edit it with your settings.
 `);
   process.exit(0);
 }
@@ -31,4 +32,22 @@ if (args.includes("--version") || args.includes("-v")) {
   process.exit(0);
 }
 
+if (args[0] === "init") {
+  const { getAssurgentHome } = await import("./src/config.ts");
+  const target = join(getAssurgentHome(), "config.json");
+
+  if (existsSync(target)) {
+    console.error(
+      `Config already exists at ${target}. Edit it directly or delete it to re-initialize.`,
+    );
+    process.exit(1);
+  }
+
+  mkdirSync(dirname(target), { recursive: true });
+  const source = join(import.meta.dirname, "config.example.json");
+  copyFileSync(source, target);
+  console.log(`Created config at ${target}. Edit it with your settings, then run "assurgent".`);
+  process.exit(0);
+}
+
 await import("./src/index.ts");

package/config.example.json

@@ -0,0 +1,26 @@
+{
+  "chat": {
+    "adapter": "telegram",
+    "telegram": {
+      "botToken": "123456:ABC-DEF...",
+      "allowedUserIds": ["YOUR_TELEGRAM_USER_ID"],
+      "placeholder": {
+        "enabled": true,
+        "text": "thinking..."
+      }
+    }
+  },
+  "agent": {
+    "adapter": "claude-code",
+    "claude-code": {
+      "model": "sonnet",
+      "maxTurns": 10,
+      "flags": ["--dangerously-skip-permissions"],
+      "claudePath": "claude"
+    }
+  },
+  "session": {
+    "turnLimit": 20
+  },
+  "workspacePath": "/path/to/your/workspace"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assurgent",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "assurgent": "./cli.ts"
@@ -8,6 +8,7 @@
   "files": [
     "cli.ts",
     "src",
+    "config.example.json",
     "README.md"
   ],
   "publishConfig": {
@@ -18,7 +19,10 @@
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "lint": "biome check .",
-    "lint:fix": "biome check . --fix"
+    "lint:fix": "biome check . --fix",
+    "release:patch": "release-it patch",
+    "release:minor": "release-it minor",
+    "release:major": "release-it major"
   },
   "dependencies": {
     "execa": "^9.5.2",
@@ -27,6 +31,7 @@
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@types/bun": "latest",
+    "release-it": "^19.2.4",
     "typescript": "^5.8.2"
   }
 }

package/src/config.test.ts

@@ -1,5 +1,8 @@
-import { describe, expect, test } from "bun:test";
-import { validateConfig } from "./config";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getAssurgentHome, loadConfig, validateConfig } from "./config";
 import type { Config } from "./config";
 
 function validConfig(): Config {
@@ -26,6 +29,82 @@ function validConfig(): Config {
   };
 }
 
+describe("getAssurgentHome", () => {
+  const originalEnv = process.env.ASSURGENT_HOME;
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      process.env.ASSURGENT_HOME = undefined;
+    } else {
+      process.env.ASSURGENT_HOME = originalEnv;
+    }
+  });
+
+  test("returns ~/.assurgent when ASSURGENT_HOME is not set", () => {
+    process.env.ASSURGENT_HOME = undefined;
+    const expected = path.join(os.homedir(), ".assurgent");
+    expect(getAssurgentHome()).toBe(expected);
+  });
+
+  test("returns ASSURGENT_HOME env var value when set", () => {
+    process.env.ASSURGENT_HOME = "/custom/assurgent/home";
+    expect(getAssurgentHome()).toBe("/custom/assurgent/home");
+  });
+});
+
+describe("loadConfig", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "assurgent-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    process.env.ASSURGENT_HOME = undefined;
+  });
+
+  function writeConfig(dir: string, config: Config): string {
+    const configPath = path.join(dir, "config.json");
+    fs.writeFileSync(configPath, JSON.stringify(config), "utf-8");
+    return configPath;
+  }
+
+  test("reads config from explicit path", () => {
+    const configPath = writeConfig(tempDir, validConfig());
+    const config = loadConfig(configPath);
+    expect(config.chat.adapter).toBe("telegram");
+    expect(config.session.turnLimit).toBe(20);
+  });
+
+  test("reads config from $ASSURGENT_HOME/config.json when no explicit path", () => {
+    process.env.ASSURGENT_HOME = tempDir;
+    writeConfig(tempDir, validConfig());
+    const config = loadConfig();
+    expect(config.chat.adapter).toBe("telegram");
+  });
+
+  test("throws with helpful error when config is missing and explicit path given", () => {
+    const missingPath = path.join(tempDir, "nonexistent.json");
+    expect(() => loadConfig(missingPath)).toThrow("Config file not found");
+  });
+
+  test("throws mentioning 'assurgent init' when config is missing", () => {
+    const missingPath = path.join(tempDir, "nonexistent.json");
+    expect(() => loadConfig(missingPath)).toThrow("assurgent init");
+  });
+
+  test("throws mentioning 'ASSURGENT_HOME' when config is missing", () => {
+    const missingPath = path.join(tempDir, "nonexistent.json");
+    expect(() => loadConfig(missingPath)).toThrow("ASSURGENT_HOME");
+  });
+
+  test("throws with config path in error message when config is missing", () => {
+    process.env.ASSURGENT_HOME = tempDir;
+    expect(() => loadConfig()).toThrow(path.join(tempDir, "config.json"));
+  });
+});
+
 describe("validateConfig", () => {
   test("accepts valid config", () => {
     expect(() => validateConfig(validConfig())).not.toThrow();

package/src/config.ts

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 /** Runtime configuration for the bot. */
@@ -31,6 +32,11 @@ export interface Config {
   workspacePath: string;
 }
 
+/** Returns the resolved ASSURGENT_HOME path. */
+export function getAssurgentHome(): string {
+  return process.env.ASSURGENT_HOME ?? path.join(os.homedir(), ".assurgent");
+}
+
 /** Fail fast with clear errors if required config fields are missing or invalid. */
 export function validateConfig(config: Config): void {
   const errors: string[] = [];
@@ -71,10 +77,12 @@ export function validateConfig(config: Config): void {
 
 /** Load and validate config from a JSON file. */
 export function loadConfig(configPath?: string): Config {
-  const resolved = configPath ?? path.resolve(import.meta.dir, "..", "config.json");
+  const resolved = configPath ?? path.join(getAssurgentHome(), "config.json");
 
   if (!fs.existsSync(resolved)) {
-    throw new Error(`Config file not found: ${resolved}`);
+    throw new Error(
+      `Config file not found: ${resolved}\nRun "assurgent init" to create one, or set ASSURGENT_HOME to point to an existing config directory.`,
+    );
   }
 
   const raw = JSON.parse(fs.readFileSync(resolved, "utf-8"));

package/src/index.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import { ClaudeCodeAdapter } from "./agent/claude-code";
 import { TelegramAdapter } from "./chat/telegram";
 import type { Config } from "./config";
-import { loadConfig } from "./config";
+import { getAssurgentHome, loadConfig } from "./config";
 import { SessionManager } from "./core/session-manager";
 import { Wrapper } from "./core/wrapper";
 import type { AgentAdapter } from "./interfaces/agent-adapter";
@@ -33,7 +33,7 @@ function createAgentAdapter(cfg: Config): AgentAdapter {
 const chat = createChatAdapter(config);
 const agent = createAgentAdapter(config);
 const sessions = new SessionManager({
-  statePath: path.join(config.workspacePath, "state"),
+  statePath: path.join(getAssurgentHome(), "state"),
 });
 
 const wrapper = new Wrapper(