assurgent 0.2.0 → 0.2.2

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/package.json

@@ -1,11 +1,16 @@
 {
   "name": "assurgent",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "bin": {
     "assurgent": "./cli.ts"
   },
-  "files": ["cli.ts", "src", "config.example.json", "README.md"],
+  "files": [
+    "cli.ts",
+    "src",
+    "config.example.json",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -14,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",
@@ -23,6 +31,7 @@
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@types/bun": "latest",
+    "release-it": "^19.2.4",
     "typescript": "^5.8.2"
   }
 }