macroclaw 0.0.0-dev

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 macrosak
+
+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,114 @@
+# Macroclaw
+
+Telegram-to-Claude-Code bridge. Bun + Grammy.
+
+Uses the Claude Code CLI (`claude -p`) rather than the Agent SDK to avoid any possible
+ToS issues with using a Claude subscription programmatically.
+
+## Vision
+
+Macroclaw is a minimal bridge between Telegram and Claude Code. It handles the parts
+that a Claude session can't: receiving messages, managing processes, scheduling tasks,
+and delivering responses.
+
+Everything else — personality, memory, skills, behavior, conventions — lives in the
+workspace. The platform stays small so the workspace can be infinitely customizable
+without touching platform code.
+
+## Architecture
+
+Macroclaw follows a **thin platform, rich workspace** design:
+
+**Platform** (this repo) — the runtime bridge:
+- Telegram bot connection and message routing
+- Claude Code process orchestration and session management
+- Background agent spawning and lifecycle
+- Cron scheduler (reads job definitions from workspace)
+- Message queue (FIFO, serial processing)
+- Timeout management and auto-retry
+
+**Workspace** — the intelligence layer, initialized from [`workspace-template/`](workspace-template/):
+- [`CLAUDE.md`](workspace-template/CLAUDE.md) — agent behavior, conventions, response style
+- [`.claude/skills/`](workspace-template/.claude/skills/) — teachable capabilities
+- [`.macroclaw/cron.json`](workspace-template/.macroclaw/cron.json) — scheduled job definitions
+- [`MEMORY.md`](workspace-template/MEMORY.md) — persistent memory
+
+### Where does a new feature belong?
+
+**Platform** when it:
+- Requires external API access (Telegram, future integrations)
+- Manages processes (spawning Claude, background agents, timeouts)
+- Operates outside Claude sessions (cron scheduling, message queuing)
+- Is a security boundary (chat authorization, workspace isolation)
+- Is bootstrap logic (workspace initialization)
+
+**Workspace** when it:
+- Defines agent behavior or personality
+- Is a convention Claude can follow via instructions
+- Can be implemented as a skill
+- Is data that Claude reads/writes (memory, tasks, cron definitions)
+- Is a formatting or response style rule
+
+> **Litmus test:** Could this feature work if you just wrote instructions in CLAUDE.md and/or created a skill? If yes → workspace. If no → platform.
+
+## Security Model
+
+Macroclaw runs with `dangerouslySkipPermissions` enabled. This is intentional — the bot
+is designed to run in an isolated environment (container or VM) where the workspace is
+the entire world. The single authorized chat ID ensures only one user can interact with
+the bot.
+
+## Requirements
+
+- [Bun](https://bun.sh/) runtime
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and logged in
+
+## Install
+
+```bash
+# Run directly (no install needed)
+TELEGRAM_BOT_TOKEN=xxx AUTHORIZED_CHAT_ID=123 bunx macroclaw
+
+# Or install globally
+bun install -g macroclaw
+export TELEGRAM_BOT_TOKEN=xxx
+export AUTHORIZED_CHAT_ID=123
+macroclaw
+```
+
+On first run, a workspace is created at `~/.macroclaw-workspace` with default config.
+Set `WORKSPACE` to use a different path. Set `MODEL` to override the Claude model.
+
+## Usage
+
+Run inside a tmux session so it survives SSH disconnects:
+
+```bash
+tmux new -s macroclaw       # start session
+macroclaw                   # run the bot
+
+# Ctrl+B, D              — detach (bot keeps running)
+# tmux attach -t macroclaw — reattach later
+# tmux kill-session -t macroclaw — stop everything
+```
+
+## Development
+
+```bash
+git clone git@github.com:macrosak/macroclaw.git
+cd macroclaw
+cp .env.example .env  # fill in real values
+bun install --frozen-lockfile
+```
+
+## Development
+
+```bash
+bun run dev    # start with watch mode
+bun test       # run tests (100% coverage enforced)
+bun run claude # open Claude Code CLI in current main session
+```
+
+## License
+
+MIT

package/bin/macroclaw.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+await import("../src/index.ts");

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "macroclaw",
+  "version": "0.0.0-dev",
+  "description": "Telegram-to-Claude-Code bridge",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "macroclaw": "./bin/macroclaw.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "workspace-template/"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun run --watch src/index.ts",
+    "check": "tsc --noEmit && biome check && bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --fix --unsafe",
+    "test": "bun test",
+    "test:integration": "bun test src/*.integration-test.ts --timeout 120000",
+    "claude": "set -a && . ./.env && set +a && cd ${WORKSPACE:-~/.macroclaw-workspace} && claude --resume $(node -p \"require('$HOME/.macroclaw/settings.json').sessionId\") --model ${MODEL:-sonnet}"
+  },
+  "dependencies": {
+    "cron-parser": "^5.5.0",
+    "grammy": "^1.39.3",
+    "openai": "^6.27.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "pinorama-client": "^0.3.0",
+    "pinorama-transport": "^0.1.4",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "bun-types": "^1.3.10",
+    "typescript": "^5.9.3"
+  }
+}