@tjamescouch/gro 1.3.2

package/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  ci:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install
+      - run: bun run build
+      - run: bun test

package/README.md

@@ -0,0 +1,218 @@
+# gro
+
+Provider-agnostic LLM runtime with context management.
+
+`gro` is a headless (no TUI) CLI that runs a single agent loop against an LLM provider, persists sessions to disk, and can connect to MCP servers for tool-use.
+
+- Works as a **one-shot** prompt runner or an **interactive** agent loop
+- **Provider-agnostic** (Anthropic / OpenAI / local OpenAI-compatible)
+- **Session persistence** to `.gro/context/<session-id>/...`
+- **Context management** via background summarization
+- **MCP support** (discovers Claude Code MCP servers by default)
+
+Repo note: agent work happens on `feature/*` branches; `main` is protected.
+
+## Install
+
+```sh
+git clone https://github.com/tjamescouch/gro.git
+cd gro
+npm install
+npx tsc
+```
+
+Requires [Bun](https://bun.sh) or Node.js 18+.
+
+## Quick start
+
+## Repo workflow (IMPORTANT)
+
+This repo is often worked on by multiple agents with an automation bot.
+
+- **Never commit on `main`.**
+- Always create a **feature branch** and commit there.
+- **Do not `git push` manually** (automation will sync your local commits).
+
+Example:
+
+```bash
+git checkout main
+git pull --ff-only
+git checkout -b feature/my-change
+
+# edit files
+git add -A
+git commit -m "<message>"
+
+# no git push
+```
+
+
+```sh
+# One-shot prompt (Anthropic by default)
+export ANTHROPIC_API_KEY=sk-...
+node dist/main.js "explain the CAP theorem in two sentences"
+
+# Pipe mode
+echo "summarize this" | node dist/main.js -p
+
+# Interactive conversation
+node dist/main.js -i
+
+# Use OpenAI
+export OPENAI_API_KEY=sk-...
+node dist/main.js -m gpt-4o "hello"
+
+# Local model via Ollama
+node dist/main.js -m llama3 "hello"
+```
+
+Tip: during development you can run directly from TypeScript:
+
+```sh
+npx tsx src/main.ts -i
+```
+
+## Providers
+
+| Provider | Flag | Models | Env var |
+|----------|------|--------|---------|
+| Anthropic | `-P anthropic` (default) | claude-sonnet-4-20250514, claude-haiku-3, etc. | `ANTHROPIC_API_KEY` |
+| OpenAI | `-P openai` | gpt-4o, o3-mini, etc. | `OPENAI_API_KEY` |
+| Local | `-P local` | llama3, mistral, qwen, etc. | none (Ollama/LM Studio) |
+
+The provider is auto-inferred from the model name. `-m claude-sonnet-4-20250514` sets provider to Anthropic. `-m gpt-4o` sets provider to OpenAI.
+
+## Options
+
+```
+-P, --provider         openai | anthropic | local (default: anthropic)
+-m, --model            model name (auto-infers provider)
+--base-url             API base URL
+--system-prompt        system prompt text
+--system-prompt-file   read system prompt from file
+--append-system-prompt append to system prompt
+--append-system-prompt-file  append system prompt from file
+--context-tokens       context window budget (default: 8192)
+--max-turns            max agentic rounds per turn (default: 10)
+--summarizer-model     model for context summarization (default: same as --model)
+--output-format        text | json | stream-json (default: text)
+--mcp-config           load MCP servers from JSON file or string
+--no-mcp               disable MCP server connections
+--no-session-persistence  don't save sessions to .gro/
+-p, --print            print response and exit (non-interactive)
+-c, --continue         continue most recent session
+-r, --resume [id]      resume a session by ID
+-i, --interactive      interactive conversation mode
+--verbose              verbose output
+-V, --version          show version
+-h, --help             show help
+```
+
+Run `node dist/main.js --help` to see the full, up-to-date CLI.
+
+## Session persistence
+
+Interactive sessions are saved to `.gro/context/<session-id>/`:
+
+```
+.gro/
+  context/
+    a1b2c3d4/
+      messages.json    # full message history
+      meta.json        # model, provider, timestamps
+```
+
+Resume the most recent session with `-c`, or a specific one with `-r <id>`.
+
+Disable with `--no-session-persistence`.
+
+## Context management
+
+In interactive mode, gro uses swim-lane summarization to manage context:
+
+- Three independent lanes (assistant / system / user) are summarized separately
+- High/low watermark hysteresis prevents thrashing
+- Summarization runs in the background and never blocks
+- Use `--summarizer-model` to route summarization to a cheaper model:
+
+```sh
+# Sonnet for reasoning, Haiku for compression
+node dist/main.js -i -m claude-sonnet-4-20250514 --summarizer-model claude-haiku-3
+```
+
+## MCP support
+
+gro discovers MCP servers from Claude Code's config (`~/.claude/settings.json`) automatically. You can also load MCP config explicitly:
+
+```sh
+node dist/main.js --mcp-config ./my-mcp-servers.json "use the filesystem tool to list files"
+```
+
+Disable MCP with `--no-mcp`.
+
+### Config discovery
+
+By default, gro attempts to discover MCP servers from Claude Code’s config:
+
+- `~/.claude/settings.json` → `mcpServers`
+
+You can also provide an explicit config file or JSON string via `--mcp-config`.
+
+### Tool availability
+
+Tools available to the model depend on which MCP servers you have configured and which are reachable.
+
+## Claude CLI compatibility
+
+gro accepts all `claude` CLI flags. Unsupported flags produce a warning and are ignored — nothing crashes.
+
+```sh
+# These all work (some with graceful degradation)
+node dist/main.js -p --model claude-sonnet-4-20250514 --max-turns 5 "hello"
+node dist/main.js --allowedTools "Bash" "hello"  # warns: --allowedTools not yet supported
+```
+
+## Architecture
+
+```
+src/
+  main.ts                    # CLI entry point, flag parsing, mode dispatch
+  session.ts                 # .gro directory and session persistence
+  logger.ts                  # Logger with color support
+  drivers/
+    types.ts                 # ChatDriver, ChatMessage, ChatOutput interfaces
+    streaming-openai.ts      # OpenAI-compatible streaming driver
+    anthropic.ts             # Native Anthropic Messages API driver
+  memory/
+    agent-memory.ts          # Abstract base with background summarization
+    advanced-memory.ts       # Swim-lane summarization with token budgeting
+    simple-memory.ts         # Unbounded message buffer
+  mcp/
+    client.ts                # MCP client manager (connect, discover, call tools)
+    index.ts                 # Re-exports
+  utils/
+    rate-limiter.ts          # Per-lane FIFO rate limiter
+    timed-fetch.ts           # Fetch with timeout
+```
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+```
+
+### Safe git workflow
+
+- Never commit directly to `main`
+- Create a `feature/*` branch for changes
+
+## License
+
+MIT
+
+## Boot
+
+For agents: see [`_base.md`](./_base.md).

package/_base.md

@@ -0,0 +1,44 @@
+# _base.md (boot)
+
+This file is the **boot context** for agents working in this repo.
+
+## Wake
+
+- On wake, before doing anything: read `~/.claude/WAKE.md`.
+- This environment is multi-agent; coordinate in AgentChat channels.
+
+## Repo workflow (IMPORTANT)
+
+This repo is often worked on by multiple agents with an automation bot.
+
+- **Never commit on `main`.**
+- Always create a **feature branch** and commit there.
+- **Do not `git push` manually** (automation will sync your local commits).
+
+Example:
+
+```bash
+git checkout main
+git pull --ff-only
+git checkout -b feature/my-change
+
+# edit files
+git add -A
+git commit -m "<message>"
+
+# no git push
+```
+
+## Agent runtime defaults
+
+- Prefer small, reviewable patches.
+- Read before you write; understand before you change.
+- Be explicit about uncertainty.
+
+## Public server notice
+
+You are connected to a **PUBLIC** AgentChat server.
+
+- Personal/open-source work only.
+- Do not paste or process confidential/proprietary code or secrets.
+- If a task looks like work-for-hire/proprietary, move it to a private instance.

package/gro

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# gro — provider-agnostic LLM CLI
+# thin dispatcher that routes to provider adapter scripts
+
+GRO_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG_DIR="${HOME}/.config/gro"
+CONFIG_FILE="${CONFIG_DIR}/config"
+
+
+# --- BRANCH WORKFLOW (IMPORTANT) ---
+#
+# If you're running gro inside the agent runner repos (e.g. as an AgentChat agent),
+# do NOT commit to main. Create/switch to a feature/* branch before making changes.
+# This is required for automation that only pushes non-main branches.
+#
+# Example:
+#   git checkout -b feature/my-task
+#
+# --- config helpers ---
+
+config_get() {
+  local key="${1:-}"
+  if [[ -z "$key" ]]; then
+    [[ -f "$CONFIG_FILE" ]] && cat "$CONFIG_FILE" || echo "(no config)"
+    return
+  fi
+  if [[ -f "$CONFIG_FILE" ]]; then
+    grep "^${key}=" "$CONFIG_FILE" 2>/dev/null | cut -d= -f2- || echo "(not set)"
+  else
+    echo "(not set)"
+  fi
+}
+
+config_set() {
+  local key="$1" value="$2"
+  mkdir -p "$CONFIG_DIR"
+  if [[ -f "$CONFIG_FILE" ]] && grep -q "^${key}=" "$CONFIG_FILE" 2>/dev/null; then
+    sed -i "s|^${key}=.*|${key}=${value}|" "$CONFIG_FILE"
+  else
+    echo "${key}=${value}" >> "$CONFIG_FILE"
+  fi
+  echo "${key}=${value}"
+}
+
+load_config_value() {
+  local key="$1" default="${2:-}"
+  if [[ -f "$CONFIG_FILE" ]]; then
+    local val
+    val=$(grep "^${key}=" "$CONFIG_FILE" 2>/dev/null | cut -d= -f2-)
+    echo "${val:-$default}"
+  else
+    echo "$default"
+  fi
+}
+
+# --- model inference ---
+
+infer_provider() {
+  local model="$1"
+  case "$model" in
+    gpt-*|o1-*|o3-*|o4-*|chatgpt-*) echo "openai" ;;
+    claude-*|sonnet*|haiku*|opus*)    echo "claude" ;;
+    gemini-*)                         echo "gemini" ;;
+    *)                                echo "" ;;
+  esac
+}
+
+# --- usage ---
+
+usage() {
+  cat <<'USAGE'
+gro — provider-agnostic LLM CLI
+
+usage:
+  gro [options] "prompt"
+  echo "prompt" | gro -p [options]
+  gro config set <key> <value>
+  gro config get [key]
+
+options:
+  -P, --provider   claude | openai | gemini (default: claude)
+  -m, --model      model name (auto-infers provider if obvious)
+  --system-prompt  system prompt text
+  -p               pipe mode (read prompt from stdin)
+  --dry-run        show resolved provider/model without calling
+  -h, --help       show this help
+
+examples:
+  gro "explain quicksort"
+  gro -P openai -m gpt-4o "explain quicksort"
+  gro -m gemini-2.0-flash "hello"
+  echo "summarize this" | gro -p --system-prompt "Be concise"
+  gro config set default-provider openai
+USAGE
+}
+
+# --- main ---
+
+main() {
+  local provider="" model="" system_prompt="" pipe=false dry_run=false
+  local -a positional=()
+
+  # config subcommand
+  if [[ "${1:-}" == "config" ]]; then
+    shift
+    local subcmd="${1:-get}"
+    shift || true
+    case "$subcmd" in
+      set) config_set "$@" ;;
+      get) config_get "$@" ;;
+      *) echo "gro config: unknown subcommand '$subcmd'" >&2; return 1 ;;
+    esac
+    return
+  fi
+
+  # parse flags
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -P|--provider)    provider="$2"; shift 2 ;;
+      -m|--model)       model="$2"; shift 2 ;;
+      --system-prompt)  system_prompt="$2"; shift 2 ;;
+      -p)               pipe=true; shift ;;
+      --dry-run)        dry_run=true; shift ;;
+      -h|--help)        usage; return 0 ;;
+      -*)               echo "gro: unknown flag '$1'" >&2; return 1 ;;
+      *)                positional+=("$1"); shift ;;
+    esac
+  done
+
+  # resolve prompt
+  local prompt=""
+  if [[ ${#positional[@]} -gt 0 ]]; then
+    prompt="${positional[*]}"
+  fi
+  if $pipe || [[ -z "$prompt" && ! -t 0 ]]; then
+    prompt=$(cat)
+  fi
+  if [[ -z "$prompt" ]]; then
+    echo "gro: no prompt provided" >&2
+    usage >&2
+    return 1
+  fi
+
+  # resolve provider
+  if [[ -z "$provider" && -n "$model" ]]; then
+    provider=$(infer_provider "$model")
+  fi
+  if [[ -z "$provider" ]]; then
+    provider=$(load_config_value default-provider "claude")
+  fi
+
+  # resolve model from config if not specified
+  if [[ -z "$model" ]]; then
+    model=$(load_config_value "${provider}.model" "")
+  fi
+
+  # dry run
+  if $dry_run; then
+    echo "provider: $provider"
+    echo "model: ${model:-(default)}"
+    echo "system-prompt: ${system_prompt:-(none)}"
+    if (( ${#prompt} > 80 )); then
+      echo "prompt: ${prompt:0:80}..."
+    else
+      echo "prompt: ${prompt}"
+    fi
+    return 0
+  fi
+
+  # find adapter
+  local adapter=""
+  for ext in sh py; do
+    if [[ -x "${GRO_DIR}/providers/${provider}.${ext}" ]]; then
+      adapter="${GRO_DIR}/providers/${provider}.${ext}"
+      break
+    fi
+  done
+
+  if [[ -z "$adapter" ]]; then
+    echo "gro: no adapter found for provider '${provider}'" >&2
+    echo "expected: ${GRO_DIR}/providers/${provider}.{sh,py}" >&2
+    return 1
+  fi
+
+  # dispatch — adapter contract:
+  #   stdin: prompt text
+  #   env: GRO_MODEL, GRO_SYSTEM_PROMPT, GRO_CONFIG_FILE
+  #   stdout: completion text
+  export GRO_MODEL="$model"
+  export GRO_SYSTEM_PROMPT="$system_prompt"
+  export GRO_CONFIG_FILE="$CONFIG_FILE"
+
+  echo "$prompt" | "$adapter"
+}
+
+main "$@"

package/owl/behaviors/agentic-turn.md

@@ -0,0 +1,43 @@
+# agentic-turn
+
+The core execution loop: send messages to the model, handle tool calls, feed results back, repeat until the model produces a final text response or the round limit is hit.
+
+## states
+
+```
+[start] -> call_model -> {has_tool_calls?}
+  yes -> execute_tools -> feed_results -> call_model
+  no  -> [done]
+
+[round_limit_exceeded] -> [done]
+```
+
+## call model
+
+1. Gather current tool definitions from MCP manager
+2. Send `memory.messages()` to the driver with tools and onToken callback
+3. If output contains text, append assistant message to memory
+4. If no tool calls, return accumulated text
+
+## execute tools
+
+1. For each tool call in the output:
+   a. Parse function name and arguments from the tool call
+   b. Log the call at debug level
+   c. Call `mcp.callTool(name, args)`
+   d. On error, capture error message as the result
+   e. Append tool result to memory with `tool_call_id` and `name`
+
+## output formatting
+
+- `text` format: tokens streamed directly to stdout via onToken
+- `stream-json` format: each token wrapped as `{"type":"token","token":"..."}` + newline
+- `json` format: final result as `{"result":"...","type":"result"}` after completion
+
+## invariants
+
+- Maximum rounds is configurable via `--max-turns` (default 10)
+- Every tool call result is fed back into memory before the next model call
+- Text output is accumulated across all rounds (model may emit text before and after tool calls)
+- Tool call argument parsing failures default to empty object `{}`
+- The onToken callback fires during streaming, so output appears incrementally

package/owl/components/cli.md

@@ -0,0 +1,37 @@
+# cli
+
+Flag parsing, configuration resolution, and mode dispatch. Entry point for the gro runtime.
+
+## capabilities
+
+- Parse CLI flags with support for value flags, boolean flags, and positional arguments
+- Auto-infer provider from model name (`claude-*` -> anthropic, `gpt-*` -> openai, `llama*` -> local)
+- Resolve system prompts from flags, files, and append combinations
+- Dispatch to interactive mode, single-shot mode, or print/pipe mode
+- Accept all `claude` CLI flags with graceful degradation for unsupported ones
+- Version display, help text
+
+## interfaces
+
+exposes:
+- `loadConfig() -> GroConfig` — parse argv into a typed config object
+- `createDriver(cfg) -> ChatDriver` — factory for the main chat driver
+- `createDriverForModel(provider, model, apiKey, baseUrl) -> ChatDriver` — factory for arbitrary driver instances
+- `createMemory(cfg, driver) -> AgentMemory` — factory for memory (SimpleMemory or AdvancedMemory)
+- `executeTurn(driver, memory, mcp, cfg) -> Promise<string>` — one agentic turn with tool loop
+- `singleShot(cfg, driver, mcp, sessionId) -> Promise<void>` — non-interactive mode
+- `interactive(cfg, driver, mcp, sessionId) -> Promise<void>` — REPL mode with auto-save
+
+depends on:
+- All other components (drivers, memory, mcp, session)
+- Node.js readline for interactive mode
+
+## invariants
+
+- `-p` forces non-interactive mode, `-i` forces interactive mode
+- Default mode is interactive when TTY and no positional args, otherwise single-shot
+- Unsupported claude flags are accepted with a warning to stderr, never crash
+- Session ID is generated once at startup and threaded through all operations
+- `--continue` and `--resume` load existing session state before the first turn
+- Interactive mode auto-saves after every turn and on close
+- MCP connections are always cleaned up (try/finally in main)

package/owl/components/drivers.md

@@ -0,0 +1,29 @@
+# drivers
+
+Chat completion backends that translate between gro's internal message format and provider-specific APIs.
+
+## capabilities
+
+- Streaming token delivery via `onToken` callback
+- Tool call parsing and accumulation from streamed deltas
+- Reasoning token forwarding via `onReasoningToken` callback
+- Provider auto-inference from model name patterns
+
+## interfaces
+
+exposes:
+- `makeStreamingOpenAiDriver(opts) -> ChatDriver` — OpenAI-compatible streaming (works with OpenAI, LM Studio, Ollama)
+- `makeAnthropicDriver(opts) -> ChatDriver` — Native Anthropic Messages API with system message separation
+- `ChatDriver.chat(messages, opts) -> Promise<ChatOutput>` — unified completion interface
+
+depends on:
+- `timed-fetch` for HTTP with timeout
+- Native `fetch` API
+
+## invariants
+
+- Drivers never mutate the input message array
+- `ChatOutput.text` contains the full accumulated text, even when tokens were streamed
+- `ChatOutput.toolCalls` is always an array (empty if no tool calls)
+- Tool call arguments are always serialized JSON strings, even if the provider returns objects
+- System messages are separated from the conversation for Anthropic (API requirement)

package/owl/components/mcp.md

@@ -0,0 +1,33 @@
+# mcp
+
+MCP client manager that connects to Model Context Protocol servers, discovers their tools, and routes tool calls during agentic turns.
+
+## capabilities
+
+- Connect to multiple MCP servers simultaneously via stdio transport
+- Discover tools from each server and merge into a unified tool list
+- Route tool calls to the correct server by tool name
+- Convert MCP tool schemas to OpenAI function-calling format for driver compatibility
+- Auto-discover servers from Claude Code's `~/.claude/settings.json`
+- Accept explicit MCP config via `--mcp-config` flag (file path or inline JSON)
+
+## interfaces
+
+exposes:
+- `McpManager.connectAll(configs) -> Promise<void>` — connect to all configured servers
+- `McpManager.getToolDefinitions() -> any[]` — merged tool list in OpenAI function-calling format
+- `McpManager.callTool(name, args) -> Promise<string>` — route and execute a tool call
+- `McpManager.hasTool(name) -> boolean` — check if a tool is available
+- `McpManager.disconnectAll() -> Promise<void>` — clean shutdown of all connections
+
+depends on:
+- `@modelcontextprotocol/sdk` — Client and StdioClientTransport
+- Server configs from Claude Code settings or explicit `--mcp-config`
+
+## invariants
+
+- Tool names are globally unique across all connected servers (last-writer-wins on collision)
+- `callTool` throws if the tool name is not found
+- Tool results are always stringified — objects are JSON.stringify'd, arrays joined
+- Disconnect is always called on process exit (interactive close handler, singleShot cleanup, error catch)
+- Server connection failures are logged and skipped, not fatal

package/owl/components/memory.md

@@ -0,0 +1,35 @@
+# memory
+
+Conversation state management with optional summarization to stay within the context window budget.
+
+## capabilities
+
+- Unbounded message buffer (SimpleMemory) for short or externally managed conversations
+- Swim-lane summarization (AdvancedMemory) with three independent lanes: assistant, system, user
+- High/low watermark hysteresis to prevent summarization thrashing
+- Background summarization that never blocks the caller (runOnce serialization)
+- Separate summarizer model support — route compression to a cheaper model
+- Session load/save to `.gro/context/<id>/`
+
+## interfaces
+
+exposes:
+- `AgentMemory.add(msg) -> Promise<void>` — append message, trigger summarization check
+- `AgentMemory.messages() -> ChatMessage[]` — current message buffer (copy)
+- `AgentMemory.load(id) -> Promise<void>` — restore from disk
+- `AgentMemory.save(id) -> Promise<void>` — persist to disk
+- `AdvancedMemory(opts)` — constructor with driver, model, summarizerDriver, summarizerModel, budget params
+- `SimpleMemory(systemPrompt?)` — constructor for no-summarization mode
+
+depends on:
+- `ChatDriver` for summarization calls (AdvancedMemory only)
+- `session` module for persistence
+
+## invariants
+
+- System prompt is always the first message if present
+- Summarization preserves the N most recent messages per lane (keepRecentPerLane)
+- Summaries are labeled: `ASSISTANT SUMMARY:`, `SYSTEM SUMMARY:`, `USER SUMMARY:`
+- Background summarization is serialized — only one runs at a time, with pending flag for re-runs
+- `messages()` always returns a copy, never the internal buffer
+- Token estimation uses character-based heuristic (avgCharsPerToken, default 4)

package/owl/components/session.md

@@ -0,0 +1,35 @@
+# session
+
+Persistence layer for saving and loading conversation state to the `.gro/` directory.
+
+## capabilities
+
+- Create and manage `.gro/context/<session-id>/` directories
+- Save message history and metadata as JSON files
+- Load sessions by ID for resumption
+- Find the most recent session for `--continue`
+- List all sessions sorted by recency
+- Generate short session IDs (UUID prefix)
+
+## interfaces
+
+exposes:
+- `ensureGroDir() -> void` — create `.gro/context/` if it doesn't exist
+- `newSessionId() -> string` — generate a short unique session ID
+- `saveSession(id, messages, meta) -> void` — write messages.json and meta.json
+- `loadSession(id) -> { messages, meta } | null` — read a session from disk
+- `findLatestSession() -> string | null` — find most recently updated session ID
+- `listSessions() -> SessionMeta[]` — all sessions sorted by recency
+
+depends on:
+- Node.js `fs` for file operations
+- Node.js `crypto` for UUID generation
+
+## invariants
+
+- Session directory is `<cwd>/.gro/context/<id>/`
+- `messages.json` contains the full ChatMessage array, JSON-serialized with 2-space indent
+- `meta.json` contains `{ id, provider, model, createdAt, updatedAt }`
+- `findLatestSession` uses filesystem mtime, not the `updatedAt` field
+- Corrupt sessions are silently skipped in `listSessions`
+- `loadSession` returns null (not throws) if the session doesn't exist