From 919c448623560e5e82415a2ff03b34c3ff12474f Mon Sep 17 00:00:00 2001 From: konard Date: Sun, 11 Jan 2026 01:20:59 +0100 Subject: [PATCH 1/5] Initial commit with task details Adding CLAUDE.md with task information for AI processing. This file will be removed when the task is complete. Issue: https://github.com/link-assistant/agent/issues/117 --- CLAUDE.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..eea9ce4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +Issue to solve: https://github.com/link-assistant/agent/issues/117 +Your prepared branch: issue-117-106178c8d9fa +Your prepared working directory: /tmp/gh-issue-solver-1768090857311 + +Proceed. From f36bc5360489f9f933d81f5d9b544bf3e91b0fa6 Mon Sep 17 00:00:00 2001 From: konard Date: Sun, 11 Jan 2026 01:25:48 +0100 Subject: [PATCH 2/5] docs: Add language-specific README.md files for JavaScript and Rust MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create js/README.md with npm-specific documentation (installation, development, publishing, project structure) - Create rust/README.md with cargo-specific documentation (build, development, implemented features, status) - Update root README.md to be common for both implementations with links to language-specific docs - Update js/package.json to include js/README.md for npm package Fixes #117 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 601 ++++++------------------------------------------ js/README.md | 198 ++++++++++++++++ js/package.json | 2 +- rust/README.md | 191 +++++++++++++++ 4 files changed, 461 insertions(+), 531 deletions(-) create mode 100644 js/README.md create mode 100644 rust/README.md diff --git a/README.md b/README.md index 236b04c..820d82c 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,65 @@ -# @link-assistant/agent +# Link Assistant Agent **A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface** -[![npm version](https://badge.fury.io/js/@link-assistant%2Fagent.svg)](https://www.npmjs.com/package/@link-assistant/agent) [![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](http://unlicense.org/) -> 🚨 **SECURITY WARNING: 100% UNSAFE AND AUTONOMOUS** 🚨 +> **SECURITY WARNING: 100% UNSAFE AND AUTONOMOUS** > > This agent operates with **ZERO RESTRICTIONS** and **FULL AUTONOMY**: > -> - ❌ **No Sandbox** - Complete unrestricted file system access -> - ❌ **No Permissions System** - No approval required for any actions -> - ❌ **No Safety Guardrails** - Can execute ANY command with full privileges -> - ⚠️ **Autonomous Execution** - Makes decisions and executes actions independently +> - No Sandbox - Complete unrestricted file system access +> - No Permissions System - No approval required for any actions +> - No Safety Guardrails - Can execute ANY command with full privileges +> - Autonomous Execution - Makes decisions and executes actions independently > > **ONLY use in isolated environments** (VMs, Docker containers) where AI agents can have unrestricted access. **NOT SAFE** for personal computers, production servers, or systems with sensitive data. -> ⚠️ **Bun-only runtime** - This package requires [Bun](https://bun.sh) and does NOT support Node.js or Deno. - -This is an MVP implementation of an OpenCode-compatible CLI agent, focused on maximum efficiency and unrestricted execution. We reproduce OpenCode's `run --format json --model opencode/grok-code` mode with: - -- ✅ **JSON Input/Output**: Compatible with `opencode run --format json --model opencode/grok-code` -- ✅ **Plain Text Input**: Also accepts plain text messages (auto-converted to JSON format) -- ✅ **Flexible Model Selection**: Defaults to free OpenCode Zen Grok Code Fast 1, supports [OpenCode Zen](https://opencode.ai/docs/zen/), [Claude OAuth](docs/claude-oauth.md), and [Groq](docs/groq.md) providers -- ✅ **No Restrictions**: Fully unrestricted file system and command execution access (no sandbox) -- ✅ **Minimal Footprint**: Built with Bun.sh for maximum efficiency -- ✅ **Full Tool Support**: 13 tools including websearch, codesearch, batch - all enabled by default -- ✅ **100% OpenCode Compatible**: All tool outputs match OpenCode's JSON format exactly -- ✅ **Internal HTTP Server**: Uses local HTTP server for session management (not exposed externally) -- ❌ **No TUI**: Pure JSON CLI interface only -- ❌ **No Sandbox**: Designed for VMs/containers where full access is acceptable -- ❌ **No LSP**: No Language Server Protocol support for diagnostics -- ❌ **No Permissions**: No permission system - full unrestricted access -- ❌ **No IDE Integration**: No IDE/editor integration features -- ❌ **No Plugins**: No plugin system -- ❌ **No Share**: No session sharing functionality -- ❌ **No External API**: Server runs only internally, not exposed to network -- ❌ **No ACP**: No Agent Client Protocol support +## Implementations -## Project Vision +This repository contains two implementations of the agent: -We're creating a slimmed-down, public domain version of OpenCode CLI focused on the "agentic run mode" for use in virtual machines, Docker containers, and other environments where unrestricted AI agent access is acceptable. This is **not** for general desktop use - it's for isolated environments where you want maximum AI agent freedom. +| Implementation | Status | Package Manager | Install Command | +|---------------|--------|-----------------|-----------------| +| [JavaScript/Bun](js/README.md) | **Production Ready** | npm | `bun install -g @link-assistant/agent` | +| [Rust](rust/README.md) | Work in Progress | cargo | `cargo install agent` (when published) | -**OpenCode Compatibility**: We maintain 100% compatibility with OpenCode's JSON event streaming format, so tools expecting `opencode run --format json --model opencode/grok-code` output will work with our agent-cli. +Both implementations aim to be fully compatible with [OpenCode](https://github.com/sst/opencode)'s `run --format json` mode. + +### JavaScript/Bun Implementation -## Design Choices +[![npm version](https://badge.fury.io/js/@link-assistant%2Fagent.svg)](https://www.npmjs.com/package/@link-assistant/agent) -### Why Bun-only? No Node.js or Deno support? +The primary implementation, feature-complete and production-ready. Requires [Bun](https://bun.sh) >= 1.0.0. -This agent is **exclusively built for Bun** for the following reasons: +```bash +# Install +bun install -g @link-assistant/agent -1. **Faster Development**: No compilation step - direct execution with `bun run` -2. **Simpler Dependencies**: Fewer dev dependencies, no TypeScript compiler overhead -3. **Performance**: Bun's fast runtime and native ESM support -4. **Minimalism**: Single runtime target keeps the codebase simple -5. **Bun Ecosystem**: Leverages Bun-specific features and optimizations +# Usage +echo "hi" | agent +``` -**Not supporting Node.js or Deno is intentional** to keep the project focused and minimal. If you need Node.js/Deno compatibility, consider using [OpenCode](https://github.com/sst/opencode) instead. +See [js/README.md](js/README.md) for full documentation. -### Architecture: Reproducing OpenCode's JSON Event Streaming +### Rust Implementation -This agent-cli reproduces the core architecture of [OpenCode](https://github.com/sst/opencode)'s `run --format json` command: +The Rust implementation provides core functionality but is still under active development. -- **Streaming JSON Events**: Instead of single responses, outputs real-time event stream -- **Event Types**: `tool_use`, `text`, `step_start`, `step_finish`, `error` -- **Session Management**: Each request gets a unique session ID -- **Tool Execution**: 13 tools with unrestricted access (bash, read, write, edit, list, glob, grep, websearch, codesearch, batch, task, todo, webfetch) -- **Compatible Format**: Events match OpenCode's JSON schema for interoperability +```bash +# Build from source +cd rust +cargo build --release +./target/release/agent -p "hello" +``` + +See [rust/README.md](rust/README.md) for full documentation. + +## Project Vision + +We're creating a slimmed-down, public domain version of OpenCode CLI focused on the "agentic run mode" for use in virtual machines, Docker containers, and other environments where unrestricted AI agent access is acceptable. This is **not** for general desktop use - it's for isolated environments where you want maximum AI agent freedom. -The agent streams events as they occur, providing the same real-time experience as OpenCode's JSON mode. +**OpenCode Compatibility**: We maintain 100% compatibility with OpenCode's JSON event streaming format, so tools expecting `opencode run --format json --model opencode/grok-code` output will work with our agent-cli. ## Features @@ -76,33 +67,10 @@ The agent streams events as they occur, providing the same real-time experience - **Plain Text Input**: Also accepts plain text messages (auto-converted to JSON format) - **Unrestricted Access**: Full file system and command execution access (no sandbox, no restrictions) - **Tool Support**: 13 tools including websearch, codesearch, batch - all enabled by default -- **Flexible Model Selection**: Defaults to free Grok Code Fast 1, supports [OpenCode Zen](https://opencode.ai/docs/zen/), [Claude OAuth](docs/claude-oauth.md), and [Groq](docs/groq.md) - see [MODELS.md](MODELS.md) -- **Bun.sh First**: Built with Bun for maximum efficiency and minimal resource usage -- **No TUI**: Pure JSON CLI interface for automation and integration +- **Flexible Model Selection**: Supports [OpenCode Zen](https://opencode.ai/docs/zen/), [Claude OAuth](docs/claude-oauth.md), [Groq](docs/groq.md), and more - see [MODELS.md](MODELS.md) - **Public Domain**: Unlicense - use it however you want -## Installation - -**Requirements:** - -- [Bun](https://bun.sh) >= 1.0.0 (Node.js and Deno are NOT supported) - -```bash -# Install Bun first if you haven't already -curl -fsSL https://bun.sh/install | bash - -# Install the package globally -bun install -g @link-assistant/agent - -# Or install locally in your project -bun add @link-assistant/agent -``` - -After installation, the `agent` command will be available globally. - -## Usage - -### Simplest Examples +## Quick Start **Plain text (easiest):** @@ -122,201 +90,13 @@ echo '{"message":"hi"}' | agent echo "hi" | agent --model opencode/grok-code ``` -### More Examples - -**Plain Text Input:** - -```bash -echo "hello world" | agent -echo "search the web for TypeScript news" | agent -``` - -**JSON Input with tool calls:** +**Direct prompt mode:** ```bash -echo '{"message":"run command","tools":[{"name":"bash","params":{"command":"ls -la"}}]}' | agent -``` - -**Using different models:** - -```bash -# Default model (free Grok Code Fast 1) -echo "hi" | agent - -# Other free models -echo "hi" | agent --model opencode/big-pickle -echo "hi" | agent --model opencode/gpt-5-nano - -# Premium models (OpenCode Zen subscription) -echo "hi" | agent --model opencode/sonnet # Claude Sonnet 4.5 -echo "hi" | agent --model opencode/haiku # Claude Haiku 4.5 -echo "hi" | agent --model opencode/opus # Claude Opus 4.1 -echo "hi" | agent --model opencode/gemini-3-pro # Gemini 3 Pro - -# Groq models (requires GROQ_API_KEY) -echo "hi" | agent --model groq/llama-3.3-70b-versatile # Llama 3.3 70B -echo "hi" | agent --model groq/llama-3.1-8b-instant # Llama 3.1 8B (fast) - -# Anthropic direct (requires ANTHROPIC_API_KEY) -echo "hi" | agent --model anthropic/claude-sonnet-4-5 # Claude Sonnet 4.5 -echo "hi" | agent --model anthropic/claude-opus-4-1 # Claude Opus 4.1 - -# Anthropic OAuth (requires Claude Pro/Max subscription) -agent auth login # Select Anthropic > Claude Pro/Max -echo "hi" | agent --model anthropic/claude-sonnet-4-5 # Uses OAuth credentials - -# Use existing Claude Code CLI credentials -echo "hi" | agent --use-existing-claude-oauth # Reads from ~/.claude/.credentials.json - -# Google Gemini (requires GOOGLE_API_KEY) -echo "hi" | agent --model google/gemini-3-pro # Gemini 3 Pro -echo "hi" | agent --model google/gemini-2.5-flash # Gemini 2.5 Flash - -# GitHub Copilot (requires Copilot subscription) -agent auth login # Select GitHub Copilot -echo "hi" | agent --model github-copilot/gpt-4o # Uses Copilot -``` - -See [MODELS.md](MODELS.md) for complete list of available models and pricing. -See [docs/groq.md](docs/groq.md) for Groq provider documentation. -See [docs/claude-oauth.md](docs/claude-oauth.md) for Claude OAuth provider documentation. - -### Direct Prompt Mode - -Use `-p`/`--prompt` to send a prompt directly without reading from stdin: - -```bash -# Direct prompt (bypasses stdin) agent -p "What is 2+2?" - -# Useful in scripts -result=$(agent -p "Summarize: $(cat file.txt)") -``` - -### Session Resume - -Resume or continue previous sessions: - -```bash -# Continue the most recent session (creates a fork with new UUID by default) -echo "Continue where we left off" | agent --continue - -# Short form -echo "Continue where we left off" | agent -c - -# Resume a specific session by ID (creates a fork with new UUID by default) -echo "Let's continue" | agent --resume ses_abc123xyz - -# Continue in the same session without forking -echo "Keep going" | agent --continue --no-fork - -# Resume specific session without forking -echo "Keep going" | agent --resume ses_abc123xyz --no-fork -``` - -**Note**: By default, `--resume` and `--continue` create a new session ID (fork) to preserve the original conversation history. Use `--no-fork` to continue in the same session. - -### CLI Options - -```bash -agent [options] - -Options: - --model Model to use in format providerID/modelID - Default: opencode/grok-code - --json-standard JSON output format standard - Choices: "opencode" (default), "claude" (experimental) - --use-existing-claude-oauth Use existing Claude OAuth credentials - from ~/.claude/.credentials.json - --system-message Full override of the system message - --system-message-file Full override of the system message from file - --append-system-message Append to the default system message - --append-system-message-file Append to the default system message from file - -Stdin Mode Options: - -p, --prompt Direct prompt (bypasses stdin reading) - --disable-stdin Disable stdin streaming (requires --prompt) - --stdin-stream-timeout Timeout in ms for stdin reading (default: none) - --interactive Accept plain text input (default: true) - --no-interactive Only accept JSON input - --auto-merge-queued-messages Merge rapidly arriving lines (default: true) - --no-auto-merge-queued-messages Treat each line as separate message - --always-accept-stdin Keep accepting input after agent finishes (default: true) - --no-always-accept-stdin Single-message mode - exit after first response - --compact-json Output compact JSON for program-to-program use - -Session Resume Options: - -r, --resume Resume a specific session by ID - By default, forks with a new UUID - -c, --continue Continue the most recent session - By default, forks with a new UUID - --no-fork When used with --resume or --continue, - continue in the same session without forking - - --help Show help - --version Show version number - -Commands: - auth login Authenticate with a provider (Anthropic, GitHub Copilot, etc.) - auth logout Remove credentials for a provider - auth list List configured credentials - auth status Check authentication status (experimental) - mcp MCP server commands -``` - -See [docs/stdin-mode.md](docs/stdin-mode.md) for comprehensive stdin mode documentation. - -### JSON Output Standards - -The agent supports two JSON output format standards via the `--json-standard` option: - -#### OpenCode Standard (default) - -The OpenCode format is the default JSON output format, compatible with `opencode run --format json`: - -```bash -echo "hi" | agent --json-standard opencode ``` -- **Format**: Pretty-printed JSON (human-readable with indentation) -- **Event Types**: `step_start`, `step_finish`, `text`, `tool_use`, `error` -- **Timestamps**: Unix milliseconds (number) -- **Session ID**: `sessionID` (camelCase) - -#### Claude Standard (experimental) - -The Claude format provides compatibility with Anthropic's Claude CLI `--output-format stream-json`: - -```bash -echo "hi" | agent --json-standard claude -``` - -- **Format**: NDJSON (Newline-Delimited JSON - compact, one JSON per line) -- **Event Types**: `init`, `message`, `tool_use`, `tool_result`, `result` -- **Timestamps**: ISO 8601 strings -- **Session ID**: `session_id` (snake_case) - -### Input Formats - -**Plain Text (auto-converted):** - -```bash -echo "your message here" | agent -``` - -**JSON Format:** - -```json -{ - "message": "Your message here", - "tools": [ - { - "name": "bash", - "params": { "command": "ls -la" } - } - ] -} -``` +See [EXAMPLES.md](EXAMPLES.md) for more usage examples. ## Supported Tools @@ -333,13 +113,13 @@ All 13 tools are **enabled by default** with **no configuration required**. See - **`glob`** - File pattern matching (`**/*.js`) - **`grep`** - Text search with regex support -- **`websearch`** ✨ - Web search via Exa API (no config needed!) -- **`codesearch`** ✨ - Code search via Exa API (no config needed!) +- **`websearch`** - Web search via Exa API (no config needed!) +- **`codesearch`** - Code search via Exa API (no config needed!) ### Execution Tools - **`bash`** - Execute shell commands -- **`batch`** ✨ - Batch multiple tool calls (no config needed!) +- **`batch`** - Batch multiple tool calls (no config needed!) - **`task`** - Launch subagent tasks ### Utility Tools @@ -347,273 +127,38 @@ All 13 tools are **enabled by default** with **no configuration required**. See - **`todo`** - Task tracking - **`webfetch`** - Fetch and process URLs -✨ = Always enabled (no experimental flags or environment variables needed) - -## MCP (Model Context Protocol) Support - -The agent supports the Model Context Protocol (MCP), allowing you to extend functionality with MCP servers. MCP enables the agent to interact with external tools and services, such as browser automation via Playwright. +## Architecture -### Installing Playwright MCP +This agent reproduces OpenCode's `run --format json` command architecture: -Microsoft's Playwright MCP server provides browser automation capabilities using Playwright. This enables the agent to interact with web pages through structured accessibility snapshots. +- **Streaming JSON Events**: Real-time event stream output +- **Event Types**: `tool_use`, `text`, `step_start`, `step_finish`, `error` +- **Session Management**: Unique session IDs for each request +- **Tool Execution**: Tools with unrestricted access +- **Compatible Format**: Events match OpenCode's JSON schema exactly -**Requirements:** +## MCP (Model Context Protocol) Support -- Node.js 18 or newer (for running the Playwright MCP server) -- Bun (for running the agent itself) +The agent supports the Model Context Protocol (MCP), allowing you to extend functionality with MCP servers such as browser automation via Playwright. -**Installation:** +**Quick setup for Playwright MCP:** ```bash -# Add Playwright MCP server to your agent configuration agent mcp add playwright npx @playwright/mcp@latest - -# Verify the configuration -agent mcp list -``` - -This will create a configuration file at `~/.config/link-assistant-agent/opencode.json` (or your system's config directory) with: - -```json -{ - "$schema": "https://opencode.ai/config.json", - "mcp": { - "playwright": { - "type": "local", - "command": ["npx", "@playwright/mcp@latest"], - "enabled": true - } - } -} -``` - -**Available Playwright Tools:** - -Once configured, the agent gains access to 22+ browser automation tools: - -- `browser_navigate` - Navigate to a URL -- `browser_click` - Click on an element -- `browser_type` - Type text into an element -- `browser_snapshot` - Capture accessibility snapshot -- `browser_take_screenshot` - Take a screenshot -- `browser_fill_form` - Fill multiple form fields -- `browser_select_option` - Select dropdown option -- `browser_hover` - Hover over element -- `browser_drag` - Drag and drop -- `browser_evaluate` - Execute JavaScript -- `browser_tabs` - Manage browser tabs -- `browser_close` - Close the browser -- `browser_wait_for` - Wait for text/element -- `browser_press_key` - Press keyboard key -- `browser_handle_dialog` - Handle browser dialogs -- `browser_network_requests` - Get network requests -- `browser_console_messages` - Get console messages -- `browser_file_upload` - Upload files -- `browser_resize` - Resize browser window -- `browser_navigate_back` - Navigate back -- `browser_install` - Install browser -- `browser_run_code` - Run Playwright code - -**Usage Example:** - -```bash -# Tell the agent to navigate to a website and take a screenshot -echo "Navigate to https://example.com and take a screenshot" | agent -``` - -The agent will automatically use the Playwright MCP tools when browser automation is needed. - -**Learn More:** - -- [Playwright MCP GitHub Repository](https://github.com/microsoft/playwright-mcp) -- [Using Playwright MCP with Claude Code](https://til.simonwillison.net/claude-code/playwright-mcp-claude-code) -- [Playwright MCP Case Study](docs/case-studies/playwright-mcp-support/case-study.md) - -### Managing MCP Servers - -**List configured servers:** - -```bash -agent mcp list -``` - -**Add a remote MCP server:** - -```bash -agent mcp add myserver --url https://example.com/mcp -``` - -**Interactive mode:** - -If you prefer an interactive setup, just run: - -```bash -agent mcp add -``` - -The interactive prompt will guide you through configuring local or remote MCP servers. - -## Examples - -See [EXAMPLES.md](EXAMPLES.md) for detailed usage examples of each tool with both agent-cli and opencode commands. - -## Testing - -```bash -# Run all tests -bun test - -# Run specific test file -bun test tests/mcp.test.js -bun test tests/websearch.tools.test.js -bun test tests/batch.tools.test.js -bun test tests/plaintext.input.test.js -``` - -For detailed testing information including how to run tests manually and trigger CI tests, see [TESTING.md](TESTING.md). - -## Maintenance - -### Development - -Run the agent in development mode: - -```bash -bun run dev -``` - -Or run directly: - -```bash -bun run js/src/index.js -``` - -### Testing - -Simply run: - -```bash -bun test -``` - -Bun automatically discovers and runs all `*.test.js` files in the project. - -### Test Coverage - -- ✅ 13 tool implementation tests -- ✅ Plain text input support test -- ✅ OpenCode compatibility tests for websearch/codesearch -- ✅ JSON standard unit tests (opencode and claude formats) -- ✅ All tests pass with 100% OpenCode JSON format compatibility - -### Publishing - -To publish a new version to npm: - -1. **Update version** in `package.json`: - - ```bash - # Update version field manually (e.g., 0.0.3 -> 0.0.4) - ``` - -2. **Commit changes**: - - ```bash - git add . - git commit -m "Release v0.0.4" - git push - ``` - -3. **Publish to npm**: - ```bash - npm publish - ``` - -The package publishes source files directly (no build step required). Bun handles TypeScript execution natively. - -## Key Features - -### No Configuration Required - -- **WebSearch/CodeSearch**: Work without `LINK_ASSISTANT_AGENT_EXPERIMENTAL_EXA` environment variable (legacy `OPENCODE_EXPERIMENTAL_EXA` still supported) -- **Batch Tool**: Always enabled, no experimental flag needed -- **All Tools**: No config files, API keys handled automatically - -### OpenCode 100% Compatible - -- All tools produce JSON output matching OpenCode's exact format -- WebSearch and CodeSearch tools are verified 100% compatible -- Tool event structure matches OpenCode specifications -- Can be used as drop-in replacement for `opencode run --format json` - -### Plain Text Support - -Both plain text and JSON input work: - -```bash -# Plain text -echo "hello" | bun run js/src/index.js - -# JSON -echo '{"message":"hello"}' | bun run js/src/index.js ``` -Plain text is automatically converted to `{"message":"your text"}` format. +See [js/README.md](js/README.md#mcp-model-context-protocol-support) for full MCP documentation. -### JSON Event Streaming Output +## Documentation -JSON output is pretty-printed for easy readability while maintaining OpenCode compatibility: - -```bash -echo "hi" | agent -``` - -Output (pretty-printed JSON events): - -```json -{ - "type": "step_start", - "timestamp": 1763618628840, - "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF", - "part": { - "id": "prt_a9fdca4e8001APEs6AriJx67me", - "type": "step-start", - ... - } -} -{ - "type": "text", - "timestamp": 1763618629886, - "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF", - "part": { - "id": "prt_a9fdca85c001bVEimWb9L3ya6T", - "type": "text", - "text": "Hi! How can I help with your coding tasks today?", - ... - } -} -{ - "type": "step_finish", - "timestamp": 1763618629916, - "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF", - "part": { - "id": "prt_a9fdca8ff0015cBrNxckAXI3aE", - "type": "step-finish", - "reason": "stop", - ... - } -} -``` - -## Architecture - -This agent-cli reproduces OpenCode's `run --format json` command architecture: - -- **Streaming JSON Events**: Real-time event stream output -- **Event Types**: `tool_use`, `text`, `step_start`, `step_finish`, `error` -- **Session Management**: Unique session IDs for each request -- **Tool Execution**: 13 tools with unrestricted access -- **Compatible Format**: Events match OpenCode's JSON schema exactly +| Document | Description | +|----------|-------------| +| [MODELS.md](MODELS.md) | Available models, providers, and pricing | +| [TOOLS.md](TOOLS.md) | Complete tool documentation | +| [EXAMPLES.md](EXAMPLES.md) | Usage examples for each tool | +| [TESTING.md](TESTING.md) | Testing guide | +| [js/README.md](js/README.md) | JavaScript/Bun implementation | +| [rust/README.md](rust/README.md) | Rust implementation | ## Files @@ -623,16 +168,14 @@ This agent-cli reproduces OpenCode's `run --format json` command architecture: - `js/src/session/` - Session management and agent implementation - `js/src/tool/` - Tool implementations - `js/tests/` - Comprehensive test suite +- `js/package.json` - npm package configuration ### Rust Implementation (rust/) -- `rust/` - Rust implementation of the CLI agent (work in progress) - -### Documentation - -- [MODELS.md](MODELS.md) - Available models and pricing -- [TOOLS.md](TOOLS.md) - Complete tool documentation -- [EXAMPLES.md](EXAMPLES.md) - Usage examples for each tool +- `rust/src/main.rs` - Main entry point +- `rust/src/cli.rs` - CLI argument parsing +- `rust/src/tool/` - Tool implementations +- `rust/Cargo.toml` - Cargo package configuration ## Reference Implementations @@ -649,8 +192,6 @@ To initialize all submodules: git submodule update --init --recursive ``` -These reference implementations provide valuable insights into different approaches for building AI agents and can serve as learning resources for developers working with this codebase. - ## License Unlicense (Public Domain) diff --git a/js/README.md b/js/README.md new file mode 100644 index 0000000..3f87f59 --- /dev/null +++ b/js/README.md @@ -0,0 +1,198 @@ +# @link-assistant/agent + +**A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface** + +[![npm version](https://badge.fury.io/js/@link-assistant%2Fagent.svg)](https://www.npmjs.com/package/@link-assistant/agent) +[![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](http://unlicense.org/) + +> This is the JavaScript/Bun implementation. See also the [Rust implementation](../rust/README.md). + +## Requirements + +- [Bun](https://bun.sh) >= 1.0.0 (Node.js and Deno are NOT supported) + +## Installation + +```bash +# Install Bun first if you haven't already +curl -fsSL https://bun.sh/install | bash + +# Install the package globally +bun install -g @link-assistant/agent + +# Or install locally in your project +bun add @link-assistant/agent +``` + +After installation, the `agent` command will be available globally. + +## Quick Start + +**Plain text (easiest):** + +```bash +echo "hi" | agent +``` + +**Simple JSON message:** + +```bash +echo '{"message":"hi"}' | agent +``` + +**With custom model:** + +```bash +echo "hi" | agent --model opencode/grok-code +``` + +## CLI Options + +```bash +agent [options] + +Options: + --model Model to use in format providerID/modelID + Default: opencode/grok-code + --json-standard JSON output format standard + Choices: "opencode" (default), "claude" (experimental) + --use-existing-claude-oauth Use existing Claude OAuth credentials + from ~/.claude/.credentials.json + --system-message Full override of the system message + --system-message-file Full override of the system message from file + --append-system-message Append to the default system message + --append-system-message-file Append to the default system message from file + +Stdin Mode Options: + -p, --prompt Direct prompt (bypasses stdin reading) + --disable-stdin Disable stdin streaming (requires --prompt) + --stdin-stream-timeout Timeout in ms for stdin reading (default: none) + --interactive Accept plain text input (default: true) + --no-interactive Only accept JSON input + --auto-merge-queued-messages Merge rapidly arriving lines (default: true) + --no-auto-merge-queued-messages Treat each line as separate message + --always-accept-stdin Keep accepting input after agent finishes (default: true) + --no-always-accept-stdin Single-message mode - exit after first response + --compact-json Output compact JSON for program-to-program use + +Session Resume Options: + -r, --resume Resume a specific session by ID + By default, forks with a new UUID + -c, --continue Continue the most recent session + By default, forks with a new UUID + --no-fork When used with --resume or --continue, + continue in the same session without forking + + --help Show help + --version Show version number + +Commands: + auth login Authenticate with a provider (Anthropic, GitHub Copilot, etc.) + auth logout Remove credentials for a provider + auth list List configured credentials + auth status Check authentication status (experimental) + mcp MCP server commands +``` + +## Development + +### Running in Development Mode + +```bash +bun run dev +``` + +Or run directly: + +```bash +bun run src/index.js +``` + +### Testing + +```bash +# Run all tests +bun test + +# Run specific test file +bun test tests/mcp.test.js +bun test tests/websearch.tools.test.js +bun test tests/batch.tools.test.js +bun test tests/plaintext.input.test.js +``` + +### Linting and Formatting + +```bash +# Run linting +bun run lint + +# Fix linting issues +bun run lint:fix + +# Format code +bun run format + +# Check formatting +bun run format:check +``` + +### Publishing + +The package uses [Changesets](https://github.com/changesets/changesets) for version management: + +1. Create a changeset: + + ```bash + bun run changeset + ``` + +2. Version the package: + + ```bash + bun run changeset:version + ``` + +3. Publish to npm: + ```bash + bun run changeset:publish + ``` + +## Project Structure + +``` +js/ +├── src/ # Source code +│ ├── index.js # Main entry point +│ ├── session/ # Session management +│ └── tool/ # Tool implementations +├── tests/ # Test files +├── experiments/ # Experimental code +├── package.json # Package configuration +└── tsconfig.json # TypeScript configuration +``` + +## Why Bun-only? + +This agent is **exclusively built for Bun** for the following reasons: + +1. **Faster Development**: No compilation step - direct execution with `bun run` +2. **Simpler Dependencies**: Fewer dev dependencies, no TypeScript compiler overhead +3. **Performance**: Bun's fast runtime and native ESM support +4. **Minimalism**: Single runtime target keeps the codebase simple +5. **Bun Ecosystem**: Leverages Bun-specific features and optimizations + +**Not supporting Node.js or Deno is intentional** to keep the project focused and minimal. + +## Documentation + +For full documentation, see the [main README](../README.md) in the repository root. + +- [Models and Pricing](../MODELS.md) +- [Tools Reference](../TOOLS.md) +- [Usage Examples](../EXAMPLES.md) +- [Testing Guide](../TESTING.md) + +## License + +Unlicense (Public Domain) diff --git a/js/package.json b/js/package.json index 190e290..87d346f 100644 --- a/js/package.json +++ b/js/package.json @@ -44,7 +44,7 @@ "files": [ "src/", "package.json", - "../README.md", + "README.md", "../MODELS.md", "../TOOLS.md", "../EXAMPLES.md", diff --git a/rust/README.md b/rust/README.md new file mode 100644 index 0000000..d8e5c48 --- /dev/null +++ b/rust/README.md @@ -0,0 +1,191 @@ +# agent (Rust) + +**A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface** + +[![Crates.io](https://img.shields.io/crates/v/agent.svg)](https://crates.io/crates/agent) +[![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](http://unlicense.org/) + +> This is the Rust implementation. See also the [JavaScript/Bun implementation](../js/README.md). + +## Status + +**Work in Progress** - The Rust implementation provides core functionality but is still under active development. For production use, consider the [JavaScript/Bun version](../js/README.md) which has full feature parity with OpenCode. + +### Implemented Features + +- JSON Input/Output compatible with OpenCode format +- Plain text input support (auto-converted to JSON) +- Core CLI argument parsing +- Session and message ID generation +- Tool framework with 7 implemented tools: + - `bash` - Execute shell commands + - `read` - Read file contents + - `write` - Write files + - `edit` - Edit files with string replacement + - `list` - List directory contents + - `glob` - File pattern matching + - `grep` - Text search with regex support + +### Not Yet Implemented + +- LLM API integration (currently echoes input) +- WebSearch and CodeSearch tools +- Batch tool +- Task tool (subagent support) +- Todo tool +- WebFetch tool +- MCP (Model Context Protocol) support +- Session resume/continue functionality +- Authentication system + +## Requirements + +- Rust 1.70 or newer +- Cargo (Rust's package manager) + +## Installation + +### From Source + +```bash +cd rust +cargo build --release + +# The binary will be at target/release/agent +./target/release/agent --help +``` + +### From crates.io (when published) + +```bash +cargo install agent +``` + +## Quick Start + +**Plain text input:** + +```bash +echo "hi" | ./target/release/agent +``` + +**JSON input:** + +```bash +echo '{"message":"hi"}' | ./target/release/agent +``` + +**Direct prompt:** + +```bash +./target/release/agent -p "hello world" +``` + +**Dry run mode (no API calls):** + +```bash +./target/release/agent --dry-run -p "test" +``` + +## CLI Options + +```bash +agent [OPTIONS] + +Options: + --model Model to use in format providerID/modelID + [default: opencode/grok-code] + --json-standard JSON output format standard + [possible values: opencode, claude] + [default: opencode] + -p, --prompt Direct prompt (bypasses stdin reading) + --system-message System message override + --append-system-message Append to system message + --verbose Enable verbose mode + --dry-run Dry run mode (simulate without API calls) + --compact-json Output compact JSON (single line) + --working-directory Working directory + -h, --help Print help + -V, --version Print version +``` + +## Development + +### Building + +```bash +cargo build +``` + +### Running Tests + +```bash +cargo test +``` + +### Running with Logging + +```bash +RUST_LOG=debug cargo run -- -p "hello" +``` + +## Project Structure + +``` +rust/ +├── src/ +│ ├── main.rs # Entry point +│ ├── cli.rs # CLI argument parsing +│ ├── error.rs # Error handling +│ ├── id.rs # ID generation (session, message, part IDs) +│ ├── util/ # Utility modules +│ └── tool/ # Tool implementations +│ ├── mod.rs # Tool registry +│ ├── context.rs +│ ├── bash.rs +│ ├── read.rs +│ ├── write.rs +│ ├── edit.rs +│ ├── list.rs +│ ├── glob.rs +│ └── grep.rs +├── changelog.d/ # Changelog fragments +├── Cargo.toml # Package configuration +└── Cargo.lock # Dependency lock file +``` + +## JSON Output Format + +The Rust implementation outputs OpenCode-compatible JSON events: + +```json +{ + "type": "step_start", + "timestamp": 1763618628840, + "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF" +} +{ + "type": "text", + "timestamp": 1763618629886, + "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF", + "text": "Agent (Rust) ready. 7 tools available." +} +{ + "type": "step_finish", + "timestamp": 1763618629916, + "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF", + "reason": "stop" +} +``` + +## Documentation + +For full documentation, see the [main README](../README.md) in the repository root. + +- [Models and Pricing](../MODELS.md) +- [Tools Reference](../TOOLS.md) +- [Usage Examples](../EXAMPLES.md) + +## License + +Unlicense (Public Domain) From 41468330fbd4865b9e12714b27905c6cec1c36df Mon Sep 17 00:00:00 2001 From: konard Date: Sun, 11 Jan 2026 01:27:09 +0100 Subject: [PATCH 3/5] chore: Add changeset for language-specific README files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- js/.changeset/language-specific-readme.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 js/.changeset/language-specific-readme.md diff --git a/js/.changeset/language-specific-readme.md b/js/.changeset/language-specific-readme.md new file mode 100644 index 0000000..5f4dbeb --- /dev/null +++ b/js/.changeset/language-specific-readme.md @@ -0,0 +1,10 @@ +--- +'@link-assistant/agent': patch +--- + +Add language-specific README.md files for JavaScript and Rust implementations + +- Create js/README.md with npm-specific documentation (installation, development, publishing) +- Create rust/README.md with cargo-specific documentation (build, features, status) +- Update root README.md to serve as common entry point for both implementations +- Update package.json files array to include js/README.md for npm package From 6b0ea6f69413a9ae27995f11bd93b32c638214e7 Mon Sep 17 00:00:00 2001 From: konard Date: Sun, 11 Jan 2026 01:30:31 +0100 Subject: [PATCH 4/5] Revert "Initial commit with task details" This reverts commit 919c448623560e5e82415a2ff03b34c3ff12474f. --- CLAUDE.md | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index eea9ce4..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,5 +0,0 @@ -Issue to solve: https://github.com/link-assistant/agent/issues/117 -Your prepared branch: issue-117-106178c8d9fa -Your prepared working directory: /tmp/gh-issue-solver-1768090857311 - -Proceed. From 6dfa1f53a908cfa0f8ac70e7c0af1624ab847ce6 Mon Sep 17 00:00:00 2001 From: konard Date: Sun, 11 Jan 2026 01:45:43 +0100 Subject: [PATCH 5/5] docs: Preserve all documentation content in language-specific READMEs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address feedback that documentation content was deleted: all previously existing docs content has been moved to js/README.md instead of being removed. The js/README.md now includes: - Full security warning with emojis - Complete feature list with checkmarks - All usage examples (model selection, session resume, etc.) - Full CLI options reference - JSON output standards (OpenCode and Claude formats) - Input formats documentation - Complete MCP documentation (Playwright tools, configuration) - Key Features section (No Config Required, OpenCode 100% Compatible) - JSON Event Streaming Output examples - Development, Testing, and Publishing sections - Why Bun-only explanation - Architecture details The root README.md serves as a common entry point with links to language-specific documentation, while preserving all essential information about the project. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 36 +++-- js/README.md | 446 +++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 457 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 820d82c..e5ce6d7 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,14 @@ [![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](http://unlicense.org/) -> **SECURITY WARNING: 100% UNSAFE AND AUTONOMOUS** +> 🚨 **SECURITY WARNING: 100% UNSAFE AND AUTONOMOUS** 🚨 > > This agent operates with **ZERO RESTRICTIONS** and **FULL AUTONOMY**: > -> - No Sandbox - Complete unrestricted file system access -> - No Permissions System - No approval required for any actions -> - No Safety Guardrails - Can execute ANY command with full privileges -> - Autonomous Execution - Makes decisions and executes actions independently +> - ❌ **No Sandbox** - Complete unrestricted file system access +> - ❌ **No Permissions System** - No approval required for any actions +> - ❌ **No Safety Guardrails** - Can execute ANY command with full privileges +> - ⚠️ **Autonomous Execution** - Makes decisions and executes actions independently > > **ONLY use in isolated environments** (VMs, Docker containers) where AI agents can have unrestricted access. **NOT SAFE** for personal computers, production servers, or systems with sensitive data. @@ -40,7 +40,12 @@ bun install -g @link-assistant/agent echo "hi" | agent ``` -See [js/README.md](js/README.md) for full documentation. +See [js/README.md](js/README.md) for full documentation including: +- Complete CLI options reference +- Model selection examples +- Session resume functionality +- MCP (Model Context Protocol) configuration +- JSON output standards (OpenCode and Claude formats) ### Rust Implementation @@ -96,7 +101,7 @@ echo "hi" | agent --model opencode/grok-code agent -p "What is 2+2?" ``` -See [EXAMPLES.md](EXAMPLES.md) for more usage examples. +See [js/README.md](js/README.md#usage) for more usage examples including model selection, session resume, and JSON output standards. ## Supported Tools @@ -113,13 +118,13 @@ All 13 tools are **enabled by default** with **no configuration required**. See - **`glob`** - File pattern matching (`**/*.js`) - **`grep`** - Text search with regex support -- **`websearch`** - Web search via Exa API (no config needed!) -- **`codesearch`** - Code search via Exa API (no config needed!) +- **`websearch`** ✨ - Web search via Exa API (no config needed!) +- **`codesearch`** ✨ - Code search via Exa API (no config needed!) ### Execution Tools - **`bash`** - Execute shell commands -- **`batch`** - Batch multiple tool calls (no config needed!) +- **`batch`** ✨ - Batch multiple tool calls (no config needed!) - **`task`** - Launch subagent tasks ### Utility Tools @@ -127,6 +132,8 @@ All 13 tools are **enabled by default** with **no configuration required**. See - **`todo`** - Task tracking - **`webfetch`** - Fetch and process URLs +✨ = Always enabled (no experimental flags or environment variables needed) + ## Architecture This agent reproduces OpenCode's `run --format json` command architecture: @@ -147,7 +154,10 @@ The agent supports the Model Context Protocol (MCP), allowing you to extend func agent mcp add playwright npx @playwright/mcp@latest ``` -See [js/README.md](js/README.md#mcp-model-context-protocol-support) for full MCP documentation. +See [js/README.md](js/README.md#mcp-model-context-protocol-support) for full MCP documentation including: +- Available Playwright tools (22+ browser automation capabilities) +- MCP server configuration +- Usage examples ## Documentation @@ -157,7 +167,7 @@ See [js/README.md](js/README.md#mcp-model-context-protocol-support) for full MCP | [TOOLS.md](TOOLS.md) | Complete tool documentation | | [EXAMPLES.md](EXAMPLES.md) | Usage examples for each tool | | [TESTING.md](TESTING.md) | Testing guide | -| [js/README.md](js/README.md) | JavaScript/Bun implementation | +| [js/README.md](js/README.md) | JavaScript/Bun implementation (full docs) | | [rust/README.md](rust/README.md) | Rust implementation | ## Files @@ -192,6 +202,8 @@ To initialize all submodules: git submodule update --init --recursive ``` +These reference implementations provide valuable insights into different approaches for building AI agents and can serve as learning resources for developers working with this codebase. + ## License Unlicense (Public Domain) diff --git a/js/README.md b/js/README.md index 3f87f59..ce539b3 100644 --- a/js/README.md +++ b/js/README.md @@ -5,8 +5,41 @@ [![npm version](https://badge.fury.io/js/@link-assistant%2Fagent.svg)](https://www.npmjs.com/package/@link-assistant/agent) [![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](http://unlicense.org/) +> 🚨 **SECURITY WARNING: 100% UNSAFE AND AUTONOMOUS** 🚨 +> +> This agent operates with **ZERO RESTRICTIONS** and **FULL AUTONOMY**: +> +> - ❌ **No Sandbox** - Complete unrestricted file system access +> - ❌ **No Permissions System** - No approval required for any actions +> - ❌ **No Safety Guardrails** - Can execute ANY command with full privileges +> - ⚠️ **Autonomous Execution** - Makes decisions and executes actions independently +> +> **ONLY use in isolated environments** (VMs, Docker containers) where AI agents can have unrestricted access. **NOT SAFE** for personal computers, production servers, or systems with sensitive data. + +> ⚠️ **Bun-only runtime** - This package requires [Bun](https://bun.sh) and does NOT support Node.js or Deno. + > This is the JavaScript/Bun implementation. See also the [Rust implementation](../rust/README.md). +This is an MVP implementation of an OpenCode-compatible CLI agent, focused on maximum efficiency and unrestricted execution. We reproduce OpenCode's `run --format json --model opencode/grok-code` mode with: + +- ✅ **JSON Input/Output**: Compatible with `opencode run --format json --model opencode/grok-code` +- ✅ **Plain Text Input**: Also accepts plain text messages (auto-converted to JSON format) +- ✅ **Flexible Model Selection**: Defaults to free OpenCode Zen Grok Code Fast 1, supports [OpenCode Zen](https://opencode.ai/docs/zen/), [Claude OAuth](../docs/claude-oauth.md), and [Groq](../docs/groq.md) providers +- ✅ **No Restrictions**: Fully unrestricted file system and command execution access (no sandbox) +- ✅ **Minimal Footprint**: Built with Bun.sh for maximum efficiency +- ✅ **Full Tool Support**: 13 tools including websearch, codesearch, batch - all enabled by default +- ✅ **100% OpenCode Compatible**: All tool outputs match OpenCode's JSON format exactly +- ✅ **Internal HTTP Server**: Uses local HTTP server for session management (not exposed externally) +- ❌ **No TUI**: Pure JSON CLI interface only +- ❌ **No Sandbox**: Designed for VMs/containers where full access is acceptable +- ❌ **No LSP**: No Language Server Protocol support for diagnostics +- ❌ **No Permissions**: No permission system - full unrestricted access +- ❌ **No IDE Integration**: No IDE/editor integration features +- ❌ **No Plugins**: No plugin system +- ❌ **No Share**: No session sharing functionality +- ❌ **No External API**: Server runs only internally, not exposed to network +- ❌ **No ACP**: No Agent Client Protocol support + ## Requirements - [Bun](https://bun.sh) >= 1.0.0 (Node.js and Deno are NOT supported) @@ -26,7 +59,9 @@ bun add @link-assistant/agent After installation, the `agent` command will be available globally. -## Quick Start +## Usage + +### Simplest Examples **Plain text (easiest):** @@ -46,6 +81,100 @@ echo '{"message":"hi"}' | agent echo "hi" | agent --model opencode/grok-code ``` +### More Examples + +**Plain Text Input:** + +```bash +echo "hello world" | agent +echo "search the web for TypeScript news" | agent +``` + +**JSON Input with tool calls:** + +```bash +echo '{"message":"run command","tools":[{"name":"bash","params":{"command":"ls -la"}}]}' | agent +``` + +**Using different models:** + +```bash +# Default model (free Grok Code Fast 1) +echo "hi" | agent + +# Other free models +echo "hi" | agent --model opencode/big-pickle +echo "hi" | agent --model opencode/gpt-5-nano + +# Premium models (OpenCode Zen subscription) +echo "hi" | agent --model opencode/sonnet # Claude Sonnet 4.5 +echo "hi" | agent --model opencode/haiku # Claude Haiku 4.5 +echo "hi" | agent --model opencode/opus # Claude Opus 4.1 +echo "hi" | agent --model opencode/gemini-3-pro # Gemini 3 Pro + +# Groq models (requires GROQ_API_KEY) +echo "hi" | agent --model groq/llama-3.3-70b-versatile # Llama 3.3 70B +echo "hi" | agent --model groq/llama-3.1-8b-instant # Llama 3.1 8B (fast) + +# Anthropic direct (requires ANTHROPIC_API_KEY) +echo "hi" | agent --model anthropic/claude-sonnet-4-5 # Claude Sonnet 4.5 +echo "hi" | agent --model anthropic/claude-opus-4-1 # Claude Opus 4.1 + +# Anthropic OAuth (requires Claude Pro/Max subscription) +agent auth login # Select Anthropic > Claude Pro/Max +echo "hi" | agent --model anthropic/claude-sonnet-4-5 # Uses OAuth credentials + +# Use existing Claude Code CLI credentials +echo "hi" | agent --use-existing-claude-oauth # Reads from ~/.claude/.credentials.json + +# Google Gemini (requires GOOGLE_API_KEY) +echo "hi" | agent --model google/gemini-3-pro # Gemini 3 Pro +echo "hi" | agent --model google/gemini-2.5-flash # Gemini 2.5 Flash + +# GitHub Copilot (requires Copilot subscription) +agent auth login # Select GitHub Copilot +echo "hi" | agent --model github-copilot/gpt-4o # Uses Copilot +``` + +See [MODELS.md](../MODELS.md) for complete list of available models and pricing. +See [docs/groq.md](../docs/groq.md) for Groq provider documentation. +See [docs/claude-oauth.md](../docs/claude-oauth.md) for Claude OAuth provider documentation. + +### Direct Prompt Mode + +Use `-p`/`--prompt` to send a prompt directly without reading from stdin: + +```bash +# Direct prompt (bypasses stdin) +agent -p "What is 2+2?" + +# Useful in scripts +result=$(agent -p "Summarize: $(cat file.txt)") +``` + +### Session Resume + +Resume or continue previous sessions: + +```bash +# Continue the most recent session (creates a fork with new UUID by default) +echo "Continue where we left off" | agent --continue + +# Short form +echo "Continue where we left off" | agent -c + +# Resume a specific session by ID (creates a fork with new UUID by default) +echo "Let's continue" | agent --resume ses_abc123xyz + +# Continue in the same session without forking +echo "Keep going" | agent --continue --no-fork + +# Resume specific session without forking +echo "Keep going" | agent --resume ses_abc123xyz --no-fork +``` + +**Note**: By default, `--resume` and `--continue` create a new session ID (fork) to preserve the original conversation history. Use `--no-fork` to continue in the same session. + ## CLI Options ```bash @@ -94,6 +223,269 @@ Commands: mcp MCP server commands ``` +See [docs/stdin-mode.md](../docs/stdin-mode.md) for comprehensive stdin mode documentation. + +### JSON Output Standards + +The agent supports two JSON output format standards via the `--json-standard` option: + +#### OpenCode Standard (default) + +The OpenCode format is the default JSON output format, compatible with `opencode run --format json`: + +```bash +echo "hi" | agent --json-standard opencode +``` + +- **Format**: Pretty-printed JSON (human-readable with indentation) +- **Event Types**: `step_start`, `step_finish`, `text`, `tool_use`, `error` +- **Timestamps**: Unix milliseconds (number) +- **Session ID**: `sessionID` (camelCase) + +#### Claude Standard (experimental) + +The Claude format provides compatibility with Anthropic's Claude CLI `--output-format stream-json`: + +```bash +echo "hi" | agent --json-standard claude +``` + +- **Format**: NDJSON (Newline-Delimited JSON - compact, one JSON per line) +- **Event Types**: `init`, `message`, `tool_use`, `tool_result`, `result` +- **Timestamps**: ISO 8601 strings +- **Session ID**: `session_id` (snake_case) + +### Input Formats + +**Plain Text (auto-converted):** + +```bash +echo "your message here" | agent +``` + +**JSON Format:** + +```json +{ + "message": "Your message here", + "tools": [ + { + "name": "bash", + "params": { "command": "ls -la" } + } + ] +} +``` + +## Supported Tools + +All 13 tools are **enabled by default** with **no configuration required**. See [TOOLS.md](../TOOLS.md) for complete documentation. + +### File Operations + +- **`read`** - Read file contents +- **`write`** - Write files +- **`edit`** - Edit files with string replacement +- **`list`** - List directory contents + +### Search Tools + +- **`glob`** - File pattern matching (`**/*.js`) +- **`grep`** - Text search with regex support +- **`websearch`** ✨ - Web search via Exa API (no config needed!) +- **`codesearch`** ✨ - Code search via Exa API (no config needed!) + +### Execution Tools + +- **`bash`** - Execute shell commands +- **`batch`** ✨ - Batch multiple tool calls (no config needed!) +- **`task`** - Launch subagent tasks + +### Utility Tools + +- **`todo`** - Task tracking +- **`webfetch`** - Fetch and process URLs + +✨ = Always enabled (no experimental flags or environment variables needed) + +## MCP (Model Context Protocol) Support + +The agent supports the Model Context Protocol (MCP), allowing you to extend functionality with MCP servers. MCP enables the agent to interact with external tools and services, such as browser automation via Playwright. + +### Installing Playwright MCP + +Microsoft's Playwright MCP server provides browser automation capabilities using Playwright. This enables the agent to interact with web pages through structured accessibility snapshots. + +**Requirements:** + +- Node.js 18 or newer (for running the Playwright MCP server) +- Bun (for running the agent itself) + +**Installation:** + +```bash +# Add Playwright MCP server to your agent configuration +agent mcp add playwright npx @playwright/mcp@latest + +# Verify the configuration +agent mcp list +``` + +This will create a configuration file at `~/.config/link-assistant-agent/opencode.json` (or your system's config directory) with: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "playwright": { + "type": "local", + "command": ["npx", "@playwright/mcp@latest"], + "enabled": true + } + } +} +``` + +**Available Playwright Tools:** + +Once configured, the agent gains access to 22+ browser automation tools: + +- `browser_navigate` - Navigate to a URL +- `browser_click` - Click on an element +- `browser_type` - Type text into an element +- `browser_snapshot` - Capture accessibility snapshot +- `browser_take_screenshot` - Take a screenshot +- `browser_fill_form` - Fill multiple form fields +- `browser_select_option` - Select dropdown option +- `browser_hover` - Hover over element +- `browser_drag` - Drag and drop +- `browser_evaluate` - Execute JavaScript +- `browser_tabs` - Manage browser tabs +- `browser_close` - Close the browser +- `browser_wait_for` - Wait for text/element +- `browser_press_key` - Press keyboard key +- `browser_handle_dialog` - Handle browser dialogs +- `browser_network_requests` - Get network requests +- `browser_console_messages` - Get console messages +- `browser_file_upload` - Upload files +- `browser_resize` - Resize browser window +- `browser_navigate_back` - Navigate back +- `browser_install` - Install browser +- `browser_run_code` - Run Playwright code + +**Usage Example:** + +```bash +# Tell the agent to navigate to a website and take a screenshot +echo "Navigate to https://example.com and take a screenshot" | agent +``` + +The agent will automatically use the Playwright MCP tools when browser automation is needed. + +**Learn More:** + +- [Playwright MCP GitHub Repository](https://github.com/microsoft/playwright-mcp) +- [Using Playwright MCP with Claude Code](https://til.simonwillison.net/claude-code/playwright-mcp-claude-code) +- [Playwright MCP Case Study](../docs/case-studies/playwright-mcp-support/case-study.md) + +### Managing MCP Servers + +**List configured servers:** + +```bash +agent mcp list +``` + +**Add a remote MCP server:** + +```bash +agent mcp add myserver --url https://example.com/mcp +``` + +**Interactive mode:** + +If you prefer an interactive setup, just run: + +```bash +agent mcp add +``` + +The interactive prompt will guide you through configuring local or remote MCP servers. + +## Key Features + +### No Configuration Required + +- **WebSearch/CodeSearch**: Work without `LINK_ASSISTANT_AGENT_EXPERIMENTAL_EXA` environment variable (legacy `OPENCODE_EXPERIMENTAL_EXA` still supported) +- **Batch Tool**: Always enabled, no experimental flag needed +- **All Tools**: No config files, API keys handled automatically + +### OpenCode 100% Compatible + +- All tools produce JSON output matching OpenCode's exact format +- WebSearch and CodeSearch tools are verified 100% compatible +- Tool event structure matches OpenCode specifications +- Can be used as drop-in replacement for `opencode run --format json` + +### Plain Text Support + +Both plain text and JSON input work: + +```bash +# Plain text +echo "hello" | bun run src/index.js + +# JSON +echo '{"message":"hello"}' | bun run src/index.js +``` + +Plain text is automatically converted to `{"message":"your text"}` format. + +### JSON Event Streaming Output + +JSON output is pretty-printed for easy readability while maintaining OpenCode compatibility: + +```bash +echo "hi" | agent +``` + +Output (pretty-printed JSON events): + +```json +{ + "type": "step_start", + "timestamp": 1763618628840, + "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF", + "part": { + "id": "prt_a9fdca4e8001APEs6AriJx67me", + "type": "step-start", + ... + } +} +{ + "type": "text", + "timestamp": 1763618629886, + "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF", + "part": { + "id": "prt_a9fdca85c001bVEimWb9L3ya6T", + "type": "text", + "text": "Hi! How can I help with your coding tasks today?", + ... + } +} +{ + "type": "step_finish", + "timestamp": 1763618629916, + "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF", + "part": { + "id": "prt_a9fdca8ff0015cBrNxckAXI3aE", + "type": "step-finish", + "reason": "stop", + ... + } +} +``` + ## Development ### Running in Development Mode @@ -121,6 +513,16 @@ bun test tests/batch.tools.test.js bun test tests/plaintext.input.test.js ``` +For detailed testing information including how to run tests manually and trigger CI tests, see [TESTING.md](../TESTING.md). + +### Test Coverage + +- ✅ 13 tool implementation tests +- ✅ Plain text input support test +- ✅ OpenCode compatibility tests for websearch/codesearch +- ✅ JSON standard unit tests (opencode and claude formats) +- ✅ All tests pass with 100% OpenCode JSON format compatibility + ### Linting and Formatting ```bash @@ -158,31 +560,49 @@ The package uses [Changesets](https://github.com/changesets/changesets) for vers bun run changeset:publish ``` +The package publishes source files directly (no build step required). Bun handles TypeScript execution natively. + +## Why Bun-only? No Node.js or Deno support? + +This agent is **exclusively built for Bun** for the following reasons: + +1. **Faster Development**: No compilation step - direct execution with `bun run` +2. **Simpler Dependencies**: Fewer dev dependencies, no TypeScript compiler overhead +3. **Performance**: Bun's fast runtime and native ESM support +4. **Minimalism**: Single runtime target keeps the codebase simple +5. **Bun Ecosystem**: Leverages Bun-specific features and optimizations + +**Not supporting Node.js or Deno is intentional** to keep the project focused and minimal. If you need Node.js/Deno compatibility, consider using [OpenCode](https://github.com/sst/opencode) instead. + ## Project Structure ``` js/ ├── src/ # Source code -│ ├── index.js # Main entry point -│ ├── session/ # Session management +│ ├── index.js # Main entry point with JSON/plain text input support +│ ├── session/ # Session management and agent implementation │ └── tool/ # Tool implementations -├── tests/ # Test files +├── tests/ # Comprehensive test suite ├── experiments/ # Experimental code -├── package.json # Package configuration +├── package.json # npm package configuration └── tsconfig.json # TypeScript configuration ``` -## Why Bun-only? +## Architecture -This agent is **exclusively built for Bun** for the following reasons: +This agent-cli reproduces the core architecture of [OpenCode](https://github.com/sst/opencode)'s `run --format json` command: -1. **Faster Development**: No compilation step - direct execution with `bun run` -2. **Simpler Dependencies**: Fewer dev dependencies, no TypeScript compiler overhead -3. **Performance**: Bun's fast runtime and native ESM support -4. **Minimalism**: Single runtime target keeps the codebase simple -5. **Bun Ecosystem**: Leverages Bun-specific features and optimizations +- **Streaming JSON Events**: Instead of single responses, outputs real-time event stream +- **Event Types**: `tool_use`, `text`, `step_start`, `step_finish`, `error` +- **Session Management**: Each request gets a unique session ID +- **Tool Execution**: 13 tools with unrestricted access (bash, read, write, edit, list, glob, grep, websearch, codesearch, batch, task, todo, webfetch) +- **Compatible Format**: Events match OpenCode's JSON schema for interoperability + +The agent streams events as they occur, providing the same real-time experience as OpenCode's JSON mode. + +## Examples -**Not supporting Node.js or Deno is intentional** to keep the project focused and minimal. +See [EXAMPLES.md](../EXAMPLES.md) for detailed usage examples of each tool with both agent-cli and opencode commands. ## Documentation