opencode-froggy 0.1.0 → 0.2.0

package/README.md

@@ -1,51 +1,266 @@
-# opencode-froggy
+<p align="center">
+  <img src="images/logo.png" alt="opencode-froggy logo" width="300">
+</p>
 
-## Overview
+<p align="center">
+  <a href="https://github.com/smartfrog/opencode-froggy/actions"><img src="https://github.com/smartfrog/opencode-froggy/workflows/CI/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/opencode-froggy"><img src="https://badge.fury.io/js/opencode-froggy.svg" alt="npm version"></a>
+</p>
 
-opencode-froggy is an OpenCode plugin that adds agents, commands, skills, and a hook system.
-It can automatically simplify changes when the session becomes idle, if files were modified
-via `write` or `edit`. Resources are loaded automatically from `agent/`, `command/`, and `skill/`.
-Hooks are loaded from OpenCode configuration directories (global and project-level).
+Plugin providing Claude Code–style hooks, specialized agents (doc-writer, code reviewer, architect, partner, etc.), dedicated commands such as simplify-code and review-pr, and tools such as gitingest.
 
-## Features
+---
 
-### Agents
+## Table of Contents
+
+- [Installation](#installation)
+- [Commands](#commands)
+- [Agents](#agents)
+- [Tools](#tools)
+  - [gitingest](#gitingest)
+  - [diff-summary](#diff-summary)
+  - [prompt-session](#prompt-session)
+  - [list-child-sessions](#list-child-sessions)
+- [Hooks](#hooks)
+  - [Configuration Locations](#configuration-locations)
+  - [Configuration File Format](#configuration-file-format)
+  - [Supported Events](#supported-events)
+  - [Conditions](#conditions)
+  - [Supported Actions](#supported-actions)
+  - [Execution Behavior](#execution-behavior)
+  - [Example Hook Configurations](#example-hook-configurations)
+- [Configuration Options](#configuration-options)
+- [License](#license)
 
-| Agent | Mode | Description |
-|-------|------|-------------|
-| `code-reviewer` | subagent | Reviews code for quality, correctness, and security. Read-only with restricted git access. |
-| `code-simplifier` | subagent | Simplifies recently modified code for clarity and maintainability while strictly preserving behavior. |
-| `doc-writer` | subagent | Technical writer that crafts clear, comprehensive documentation (README, API docs, architecture docs, user guides). |
+---
+
+## Installation
+
+### From npm (recommended)
+
+Add the plugin to your OpenCode configuration file (`opencode.json`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-froggy"]
+}
+```
+
+### From local files
 
-### Commands
+Alternatively, clone or copy the plugin files to one of these directories:
+
+- **Project-local**: `.opencode/plugin/opencode-froggy/`
+- **Global**: `~/.config/opencode/plugin/opencode-froggy/`
+
+---
+
+## Commands
 
 | Command | Description | Agent |
 |---------|-------------|-------|
-| `/commit` | Create a commit with appropriate message, create branch if on main/master, and push | `build` |
+| `/commit-push` | Stage, commit, and push changes with user confirmation | `build` |
+| `/doc-changes` | Update documentation based on uncommitted changes (new features only) | `doc-writer` |
 | `/review-changes` | Review uncommitted changes (staged + unstaged, including untracked files) | `code-reviewer` |
 | `/review-pr <source> <target>` | Review changes from source branch into target branch | `code-reviewer` |
+| `/send-to [agent] <message>` | Send a message to a child session (subagent) to continue the conversation | - |
 | `/simplify-changes` | Simplify uncommitted changes (staged + unstaged, including untracked files) | `code-simplifier` |
 | `/tests-coverage` | Run the full test suite with coverage report and suggest fixes for failures | `build` |
 
-### Skills
+---
+
+## Agents
+
+| Agent | Mode | Description |
+|-------|------|-------------|
+| `architect` | subagent | Strategic technical advisor providing high-leverage guidance on architecture, code structure, and complex engineering trade-offs. Read-only. |
+| `code-reviewer` | subagent | Reviews code for quality, correctness, and security. Read-only with restricted git access. |
+| `code-simplifier` | subagent | Simplifies recently modified code for clarity and maintainability while strictly preserving behavior. |
+| `doc-writer` | subagent | Technical writer that crafts clear, comprehensive documentation (README, API docs, architecture docs, user guides). |
+| `partner` | subagent | Strategic ideation partner that breaks frames, expands solution spaces, and surfaces non-obvious strategic options. Read-only. |
+| `rubber-duck` | subagent | Strategic thinking partner for exploratory dialogue. Challenges assumptions, asks pointed questions, and sharpens thinking through conversational friction. Read-only. |
+
+---
+
+## Tools
+
+### gitingest
+
+Fetch a GitHub repository's full content via gitingest.com. Returns summary, directory tree, and file contents optimized for LLM analysis. Use when you need to understand an external repository's structure or code.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | `string` | Yes | - | The GitHub repository URL to fetch |
+| `maxFileSize` | `number` | No | `50000` | Maximum file size in bytes to include |
+| `pattern` | `string` | No | `""` | Glob pattern to filter files (e.g., `*.ts`, `src/**/*.py`) |
+| `patternType` | `"include"` \| `"exclude"` | No | `"exclude"` | Whether to include or exclude files matching the pattern |
+
+#### Usage Examples
+
+```typescript
+// Fetch entire repository
+gitingest({ url: "https://github.com/user/repo" })
+
+// Only TypeScript files
+gitingest({ 
+  url: "https://github.com/user/repo",
+  pattern: "*.ts",
+  patternType: "include"
+})
+
+// Exclude test files
+gitingest({
+  url: "https://github.com/user/repo", 
+  pattern: "*.test.ts",
+  patternType: "exclude"
+})
+
+// Increase max file size to 100KB
+gitingest({
+  url: "https://github.com/user/repo",
+  maxFileSize: 100000
+})
+```
+
+#### Limitations
+
+- Content is truncated to 300k characters (server-side limit from gitingest.com)
+- For large repositories, use pattern filtering to focus on relevant files
+- The `maxFileSize` parameter controls individual file size, not total output size
+
+---
+
+### diff-summary
+
+Generate a structured summary of git diffs. Use for reviewing branch comparisons or working tree changes. Returns stats, commits, files changed, and full diff in a structured markdown format.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `source` | `string` | No | - | Source branch to compare (e.g., `feature-branch`). If omitted, analyzes working tree changes. |
+| `target` | `string` | No | `main` | Target branch to compare against |
+| `remote` | `string` | No | `origin` | Git remote name |
+
+#### Usage Examples
 
-The plugin supports skills loaded from `skill/<name>/SKILL.md` within the plugin directory. No skills are included by default. The plugin exposes a `skill` tool that lists available skills and returns their instructions.
+```typescript
+// Analyze working tree changes (staged, unstaged, and untracked files)
+diffSummary({})
 
-To add your own skills, create a directory structure like:
+// Compare feature branch against main
+diffSummary({ source: "feature-branch" })
 
+// Compare feature branch against develop
+diffSummary({ 
+  source: "feature-branch",
+  target: "develop"
+})
+
+// Compare branches on a different remote
+diffSummary({
+  source: "feature-branch",
+  target: "main",
+  remote: "upstream"
+})
+```
+
+#### Output Structure
+
+**For branch comparisons:**
+- Stats Overview: Summary of changes (insertions, deletions)
+- Commits to Review: List of commits in the range
+- Files Changed: List of modified files
+- Full Diff: Complete diff with context
+
+**For working tree changes:**
+- Status Overview: Git status output
+- Staged Changes: Stats, files, and diff for staged changes
+- Unstaged Changes: Stats, files, and diff for unstaged changes
+- Untracked Files: List and diffs for new untracked files
+
+#### Notes
+
+- When comparing branches, the tool fetches from the remote before generating the diff
+- Diffs include 5 lines of context and function context for better readability
+
+---
+
+### prompt-session
+
+Send a message to a child session (subagent) to continue the conversation. Useful for iterating with subagents without creating new sessions.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `message` | `string` | Yes | - | The message to send to the child session |
+| `sessionId` | `string` | No | - | The child session ID to target. If omitted, targets the last child session. |
+
+#### Usage Examples
+
+```typescript
+// Send a message to the last child session
+promptSession({ message: "Please also add unit tests for the new function" })
+
+// Send a message to a specific child session
+promptSession({
+  message: "Can you clarify the error handling approach?",
+  sessionId: "abc123"
+})
 ```
-skill/
-  my-skill/
-    SKILL.md
+
+#### Behavior
+
+- If `sessionId` is not provided, the tool automatically targets the most recently created child session
+- Returns the text response from the child session
+- Returns an error message if no child session exists for the current session
+
+---
+
+### list-child-sessions
+
+List all child sessions (subagents) of the current session. Useful for finding specific sessions to target with `prompt-session`.
+
+#### Parameters
+
+This tool takes no parameters.
+
+#### Usage Examples
+
+```typescript
+// List all child sessions
+listChildSessions()
 ```
 
-The `SKILL.md` file supports YAML frontmatter with `name` and `description` fields. The name defaults to the directory name if not specified.
+#### Output
 
-### Hooks
+Returns a formatted list of child sessions with:
+- Session ID
+- Session title
+- Created and updated timestamps
+
+Example output:
+```
+Child sessions (2):
+
+1. [abc123] Code Review Session
+   Created: 2024-01-15T10:30:00Z | Updated: 2024-01-15T10:35:00Z
+
+2. [def456] Architecture Discussion
+   Created: 2024-01-15T11:00:00Z | Updated: 2024-01-15T11:15:00Z
+```
+
+---
+
+## Hooks
 
 Hooks run actions on session events. Configuration is loaded from standard OpenCode configuration directories.
 
-#### Configuration locations
+### Configuration Locations
 
 Hooks are loaded from these locations (in order, merged together):
 
@@ -59,11 +274,11 @@ On Windows, `~/.config` is preferred for cross-platform consistency. If hooks ex
 
 Global hooks run first, then project hooks are added. Hooks from both sources are combined (not overridden).
 
-#### Configuration file
+### Configuration File Format
 
-- YAML frontmatter must include a `hooks` list.
-- Each hook defines `event`, `actions`, and optional `conditions`.
-- Hooks for the same event run in declaration order.
+- YAML frontmatter must include a `hooks` list
+- Each hook defines `event`, `actions`, and optional `conditions`
+- Hooks for the same event run in declaration order
 
 Example `hooks.md`:
 
@@ -77,7 +292,7 @@ hooks:
 ---
 ```
 
-#### Supported events
+### Supported Events
 
 | Event | Description |
 |-------|-------------|
@@ -89,17 +304,19 @@ hooks:
 | `tool.after.*` | Emitted after any tool executes |
 | `tool.after.<name>` | Emitted after a specific tool (e.g., `tool.after.edit`) |
 
-**Tool hook execution order:**
+#### Tool Hook Execution Order
+
 1. `tool.before.*` (all tools)
 2. `tool.before.<name>` (specific tool)
 3. *(tool executes)*
 4. `tool.after.*` (all tools)
 5. `tool.after.<name>` (specific tool)
 
-**Blocking tools with exit code 2:**
+#### Blocking Tools with Exit Code 2
+
 For `tool.before.*` and `tool.before.<name>` hooks, a bash action returning exit code 2 will block the tool from executing. The stderr output is displayed to the user as the block reason.
 
-#### Conditions
+### Conditions
 
 | Condition | Description |
 |-----------|-------------|
@@ -108,115 +325,126 @@ For `tool.before.*` and `tool.before.<name>` hooks, a bash action returning exit
 
 All listed conditions must pass for the hook to run.
 
-Code extensions treated as "code" by default:
+**Code extensions treated as "code":**
+
 `ts`, `tsx`, `js`, `jsx`, `mjs`, `cjs`, `json`, `yml`, `yaml`, `toml`, `css`, `scss`, `sass`, `less`, `html`, `vue`, `svelte`, `go`, `rs`, `c`, `h`, `cpp`, `cc`, `cxx`, `hpp`, `java`, `py`, `rb`, `php`, `sh`, `bash`, `kt`, `kts`, `swift`, `m`, `mm`, `cs`, `fs`, `scala`, `clj`, `hs`, `lua`.
 
-#### Supported actions
-
-- **Command**
-  - Short form: `command: simplify-changes`
-  - With args:
-    - `command:`
-      - `name: review-pr`
-      - `args: "main feature"`
-  - If the command exists in config, the plugin reuses its `agent` and `model`.
-- **Skill**
-  - `skill: my-skill`
-  - The name must match a loaded skill. The plugin prompts the session to call the `skill` tool for that skill.
-- **Tool**
-  - `tool:`
-    - `name: bash`
-    - `args: { command: "echo done" }`
-  - The plugin prompts the session to use the tool with these arguments.
-- **Bash**
-  Executes a shell command directly without involving the LLM. Useful for running linters, formatters, build scripts, or custom automation.
-
-  **Configuration:**
-  ```yaml
-  # Short form
-  - bash: "npm run lint"
-
-  # Long form with custom timeout
-  - bash:
-      command: "$OPENCODE_PROJECT_DIR/.opencode/hooks/init.sh"
-      timeout: 30000  # milliseconds (default: 60000)
-  ```
-
-  **Environment variables:**
-
-  The plugin injects these variables into the child process environment before executing the command:
-
-  | Variable | Value | Use case |
-  |----------|-------|----------|
-  | `OPENCODE_PROJECT_DIR` | Absolute path to the project (e.g., `/home/user/project`) | Reference project files from scripts located elsewhere |
-  | `OPENCODE_SESSION_ID` | The OpenCode session identifier | Logging, tracing, or conditioning actions based on session |
-
-  Example usage in a script:
-  ```bash
-  #!/bin/bash
-  # Access variables directly
-  echo "Project: $OPENCODE_PROJECT_DIR"
-  echo "Session: $OPENCODE_SESSION_ID"
-
-  # Access a project file
-  cat "$OPENCODE_PROJECT_DIR/package.json"
-
-  # Log with session ID
-  echo "[$OPENCODE_SESSION_ID] Hook executed" >> /tmp/opencode.log
-  ```
-
-  **Stdin JSON context:**
-  The command receives a JSON object via stdin with session context:
-  ```json
-  {
-    "session_id": "abc123",
-    "event": "session.idle",
-    "cwd": "/path/to/project",
-    "files": ["src/index.ts", "src/utils.ts"]
-  }
-  ```
-  The `files` array is only present for `session.idle` events and contains paths modified via `write` or `edit`.
-
-  For tool hooks (`tool.before.*`, `tool.after.*`), additional fields are provided:
-  ```json
-  {
-    "session_id": "abc123",
-    "event": "tool.before.write",
-    "cwd": "/path/to/project",
-    "tool_name": "write",
-    "tool_args": { "filePath": "src/index.ts", "content": "..." }
-  }
-  ```
-
-  **Environment variables vs stdin JSON:**
-  - **Environment variables**: Direct access via `$VAR`, convenient for simple values like paths and IDs
-  - **Stdin JSON**: Contains richer context (event type, working directory, modified files), requires parsing with `jq` or similar
-
-  Both mechanisms are complementary. Use environment variables for quick access to project path and session ID; use stdin JSON when you need event details or the list of modified files.
-
-  **Exit codes:**
-  | Code | Behavior |
-  |------|----------|
-  | `0` | Success, continue to next action |
-  | `2` | Blocking error, stop remaining actions in this hook |
-  | Other | Non-blocking error, log warning and continue |
-
-  **Result feedback:**
-  Bash hook results are automatically sent back to your session, so you can see what happened:
-  ```
-  [BASH HOOK ✓] npm run lint
-  Exit: 0 | Duration: 1234ms
-  Stdout: All files passed linting
-  ```
-  The feedback includes a status icon (✓ success, ✗ failure), exit code, execution duration, and stdout/stderr output (truncated to 500 characters). This message appears in your session but does not trigger a response from the assistant.
-
-#### Execution behavior
-
-- Action errors are logged and do not stop later actions.
-- `session.idle` only fires if files were modified via `write` or `edit`; the session's modified file list is cleared after the hook runs.
-- The main session is set on `session.created` with no parent, or on the first `session.idle` if needed.
-
-Example with multiple hooks:
+### Supported Actions
+
+#### Command Action
+
+Execute a plugin command.
+
+```yaml
+# Short form
+- command: simplify-changes
+
+# With arguments
+- command:
+    name: review-pr
+    args: "main feature"
+```
+
+If the command exists in config, the plugin reuses its `agent` and `model`.
+
+#### Tool Action
+
+Prompt the session to use a tool with specific arguments.
+
+```yaml
+- tool:
+    name: bash
+    args: { command: "echo done" }
+```
+
+#### Bash Action
+
+Execute a shell command directly without involving the LLM. Useful for running linters, formatters, build scripts, or custom automation.
+
+**Configuration:**
+
+```yaml
+# Short form
+- bash: "npm run lint"
+
+# Long form with custom timeout
+- bash:
+    command: "$OPENCODE_PROJECT_DIR/.opencode/hooks/init.sh"
+    timeout: 30000  # milliseconds (default: 60000)
+```
+
+**Environment Variables:**
+
+The plugin injects these variables into the child process environment:
+
+| Variable | Value | Use case |
+|----------|-------|----------|
+| `OPENCODE_PROJECT_DIR` | Absolute path to the project (e.g., `/home/user/project`) | Reference project files from scripts located elsewhere |
+| `OPENCODE_SESSION_ID` | The OpenCode session identifier | Logging, tracing, or conditioning actions based on session |
+
+**Stdin JSON Context:**
+
+The command receives a JSON object via stdin with session context:
+
+```json
+{
+  "session_id": "abc123",
+  "event": "session.idle",
+  "cwd": "/path/to/project",
+  "files": ["src/index.ts", "src/utils.ts"]
+}
+```
+
+The `files` array is only present for `session.idle` events and contains paths modified via `write` or `edit`.
+
+For tool hooks (`tool.before.*`, `tool.after.*`), additional fields are provided:
+
+```json
+{
+  "session_id": "abc123",
+  "event": "tool.before.write",
+  "cwd": "/path/to/project",
+  "tool_name": "write",
+  "tool_args": { "filePath": "src/index.ts", "content": "..." }
+}
+```
+
+**Environment Variables vs Stdin JSON:**
+
+- **Environment variables**: Direct access via `$VAR`, convenient for simple values like paths and IDs
+- **Stdin JSON**: Contains richer context (event type, working directory, modified files), requires parsing with `jq` or similar
+
+Both mechanisms are complementary. Use environment variables for quick access to project path and session ID; use stdin JSON when you need event details or the list of modified files.
+
+**Exit Codes:**
+
+| Code | Behavior |
+|------|----------|
+| `0` | Success, continue to next action |
+| `2` | Blocking error, stop remaining actions in this hook |
+| Other | Non-blocking error, log warning and continue |
+
+**Result Feedback:**
+
+Bash hook results are automatically sent back to your session:
+
+```
+[BASH HOOK ✓] npm run lint
+Exit: 0 | Duration: 1234ms
+Stdout: All files passed linting
+```
+
+The feedback includes a status icon (✓ success, ✗ failure), exit code, execution duration, and stdout/stderr output (truncated to 500 characters). This message appears in your session but does not trigger a response from the assistant.
+
+### Execution Behavior
+
+- Action errors are logged and do not stop later actions
+- `session.idle` only fires if files were modified via `write` or `edit`; the session's modified file list is cleared after the hook runs
+- The main session is set on `session.created` with no parent, or on the first `session.idle` if needed
+
+### Example Hook Configurations
+
+#### Basic Multi-Hook Setup
 
 ```markdown
 ---
@@ -238,9 +466,8 @@ hooks:
 ---
 ```
 
-#### Example bash hook scripts
+#### Simple Lint-on-Idle Hook
 
-**Simple lint-on-idle hook:**
 ```yaml
 hooks:
   - event: session.idle
@@ -249,7 +476,10 @@ hooks:
       - bash: "npm run lint --fix"
 ```
 
-**Custom initialization script (`.opencode/hooks/init.sh`):**
+#### Custom Initialization Script
+
+`.opencode/hooks/init.sh`:
+
 ```bash
 #!/bin/bash
 set -e
@@ -269,7 +499,8 @@ echo "Project: $OPENCODE_PROJECT_DIR"
 exit 0
 ```
 
-**Conditional blocking based on lint errors:**
+#### Conditional Blocking Based on Lint Errors
+
 ```bash
 #!/bin/bash
 # Run linter and block if critical errors found
@@ -281,9 +512,8 @@ else
 fi
 ```
 
-#### Example tool hooks
+#### Block Modifications to Sensitive Files
 
-**Block modifications to sensitive files:**
 ```yaml
 hooks:
   - event: tool.before.write
@@ -305,7 +535,8 @@ hooks:
           fi
 ```
 
-**Auto-format TypeScript files after write:**
+#### Auto-Format TypeScript Files After Write
+
 ```yaml
 hooks:
   - event: tool.after.write
@@ -317,7 +548,8 @@ hooks:
           fi
 ```
 
-**Log all tool executions:**
+#### Log All Tool Executions
+
 ```yaml
 hooks:
   - event: tool.before.*
@@ -328,112 +560,17 @@ hooks:
           echo "[$(date)] Tool: $tool" >> /tmp/opencode-tools.log
 ```
 
-## Installation
-
-Add the plugin to your OpenCode configuration file at `~/.config/opencode/opencode.json`:
-
-```json
-{
-  "plugin": {
-    "froggy": {
-      "path": "/path/to/opencode-froggy"
-    }
-  }
-}
-```
-
-Or if published to npm:
-
-```json
-{
-  "plugin": {
-    "froggy": {
-      "module": "opencode-froggy"
-    }
-  }
-}
-```
-
-## Usage
-
-### Review uncommitted changes
-
-```
-/review-changes
-```
-
-Reviews all staged, unstaged, and untracked changes in the working tree.
-
-### Review a pull request
-
-```
-/review-pr feature-branch main
-```
-
-Fetches and reviews changes from `origin/feature-branch` into `origin/main`.
-
-### Simplify uncommitted changes
-
-```
-/simplify-changes
-```
-
-Analyzes and simplifies all uncommitted changes while preserving behavior.
-
-### Commit and push
-
-```
-/commit
-```
-
-Creates a branch (if on main/master), commits with an appropriate message, and pushes.
-
-### Run tests with coverage
-
-```
-/tests-coverage
-```
-
-Runs the test suite with coverage and suggests fixes for failures.
+---
 
 ## Configuration Options
 
-The plugin does not require additional configuration. Agents, commands, and skills are loaded automatically from the `agent/`, `command/`, and `skill/` directories within the plugin. Hooks are loaded from the standard OpenCode configuration directories (see Hooks section above).
+The plugin does not require additional configuration. Agents, commands, and skills are loaded automatically from the `agent/`, `command/`, and `skill/` directories within the plugin. Hooks are loaded from the standard OpenCode configuration directories (see [Hooks](#hooks) section).
 
 ### Supported Code File Extensions
 
-The `hasCodeChange` condition checks file extensions against the default set listed in the Hooks section. Hooks without any conditions still trigger on any modified file paths tracked via `write` or `edit` in the current session.
-
-## Development
-
-### Prerequisites
-
-- Node.js 18+
-- npm
-
-### Setup
-
-```bash
-npm install
-```
+The `hasCodeChange` condition checks file extensions against the default set listed in the [Conditions](#conditions) section. Hooks without any conditions still trigger on any modified file paths tracked via `write` or `edit` in the current session.
 
-### Build
-
-```bash
-npm run build
-```
-
-### Run tests
-
-```bash
-npm test
-```
-
-### Type checking
-
-```bash
-npm run typecheck
-```
+---
 
 ## License