@bojackduy/opencode-loopd 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 1.0.0 (2026-08-21)
+
+### Features
+
+- **Goal lifecycle**: create, active, pause, resume, retry, clear, complete, blocked
+- **Engine-driven loop**: idle detection → continuation steering → automatic re-prompt
+- **Continuation steering**: accumulated context (progress history, transcript tail, inbox messages)
+- **Worker tools**: get_goal, report_goal_progress, complete_goal, block_goal (clarification via OpenCode's native `question` tool)
+- **Owner tools**: list_background_goals, inspect_background_goal, read_goal_transcript, send_goal_input, pause_goal, resume_goal, clear_goal
+- **Inbox system**: bidirectional user↔child messaging
+- **Dashboard**: goal list, detail view, question banner, mode switch (NORMAL/INSERT), keyboard shortcuts
+- **Safety defaults**: maxTurns=50, maxFailures=3
+- **Server/TUI debug logging**: /tmp/loopd-server.log, /tmp/loopd-tui.log
+- **Skill file**: agent guidance for goal lifecycle at ~/.config/opencode/skills/loopd/SKILL.md
+
+### Architecture
+
+- Engine-driven loop (same as Codex): idle event → continuation steering → child continues
+- Parent visibility layer: owner tools read child transcript, progress, and state
+- Bidirectional messaging: inbox system for user→child instructions
+- Awaiting_user status: child can pause and ask questions
+
+
+## 1.0.1 (2026-08-21)
+
+### Changed
+
+- Removed redundant `ask_user` tool and `awaiting_user` status. Workers now use OpenCode's native `question` tool for clarification — questions appear in the TUI footer as blocker tabs, no goal status change needed.
+- Removed `:answer` dashboard command (native question answers flow through OpenCode).

package/LICENSE

@@ -0,0 +1,21 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 Duy Trinh
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+---
+This project also bundles installer and runtime dependencies with their
+own licenses. See package.json for details.

package/README.md

@@ -0,0 +1,138 @@
+# opencode-loopd
+
+**Background goal engine for OpenCode** — run long-running tasks as autonomous child sessions while the main chat stays interactive.
+
+## What it is
+
+opencode-loopd is an OpenCode plugin that creates background goals with dedicated worker sessions. The parent chat stays interactive while work happens behind the scenes. You can observe, steer, pause, or stop goals at any time.
+
+## Install
+
+### Manual
+
+Add to `~/.config/opencode/opencode.jsonc`:
+
+```json
+{
+  "plugin": [
+    "/Users/you/Code/opencode-loopd"
+  ]
+}
+```
+
+### npx (recommended)
+
+```bash
+npx -y @bojackduy/opencode-loopd@latest
+```
+
+Run the same command again to update. Then restart OpenCode.
+
+### npm global
+
+```bash
+npm install -g @bojackduy/opencode-loopd@latest
+opencode-loopd
+```
+
+Then restart OpenCode.
+
+## Usage
+
+### Create a goal
+
+From any session, tell the agent:
+
+```
+Create a background goal to fetch the latest AI news and save 10 items to ai-news.md
+```
+
+The agent will use `loopd_create_goal` to start the goal.
+
+### Monitor with dashboard
+
+Press `Ctrl+L` or open the command palette → "Loop Dashboard".
+
+Dashboard shortcuts:
+- `j/k` — move selection
+- `g/G` — jump to top/bottom
+- `o` — open child session (full transcript)
+- `p/r/R/x` — pause / resume / retry / clear selected goal
+- `?` — toggle help
+- `:` — enter insert mode (send message, control commands)
+- `Ctrl+N` — return to normal mode
+- `q` — close
+
+### Inspect from main agent
+
+The main agent can use these tools:
+
+```
+list_background_goals()          — status snapshot
+inspect_background_goal()        — full detail
+read_goal_transcript()           — child session transcript
+send_goal_input(goalID, msg)     — send instruction to child
+pause_goal(goalID)               — pause
+resume_goal(goalID)              — resume
+clear_goal(goalID)               — stop and remove
+```
+
+### Worker tools (child session)
+
+The child worker has these tools:
+
+- `get_goal` — read objective, state, criteria
+- `report_goal_progress` — report what was done
+- `complete_goal` — mark done (must pass checks)
+- `block_goal` — mark blocked (needs user)
+- `question` (OpenCode builtin) — ask the user; appears in the TUI footer
+
+## Architecture
+
+```
+Main session (parent)
+  ↕ owner tools: inspect, steer, pause
+Loopd engine
+  ↕ continuation steering + accumulated context
+Child worker session
+  ↕ goal tools: progress, complete, block, ask
+```
+
+- **Engine-driven loop**: child works → idle detected → engine re-prompts with accumulated context
+- **Parent visibility**: owner tools read child transcript, progress history, and current state
+- **Bidirectional messaging**: inbox system for user↔child instructions
+- **Safety defaults**: maxTurns=50, maxFailures=3
+
+## Example
+
+```
+# Create a goal
+goal: "Find all .ts files in src/, count lines, write summary to line-counts.md"
+
+# Engine loops automatically
+Turn 1: child counts files → reports progress
+Turn 2: child sees "batch 1 done" → continues
+Turn 3: child finishes → calls complete_goal
+
+# Parent inspects at any time
+inspect_background_goal()  → shows turn count, progress, status
+read_goal_transcript()     → shows child's work
+```
+
+## Configuration
+
+Goals accept these config options:
+
+| Option | Default | Description |
+|---|---|---|
+| `maxTurns` | 50 | Max continuation turns |
+| `maxFailures` | 3 | Max consecutive failures before block |
+| `maxNoProgress` | 3 | Turns without progress before block |
+| `timeoutMs` | 300000 | Per-turn timeout (5 min) |
+| `compactEvery` | — | Compact child session every N turns |
+| `checks` | [] | Shell commands that must pass for completion |
+| `progressFile` | — | Markdown file for transaction state |
+
+## License
+
+AGPL-3.0-only — see [LICENSE](./LICENSE).

package/commands/goal.md

@@ -0,0 +1,20 @@
+---
+description: Create a new background loop goal. Asks clarifying questions, then spawns an autonomous worker session via loopd.
+---
+
+Create a new background loop goal using the `loopd_create_goal` tool.
+
+First, gather what you need to craft a good goal:
+- If the user gave a vague objective, ask 1–3 short clarifying questions (what to accomplish, where, and how they'll verify it).
+- If the user was specific, skip straight to creating it.
+
+When you have enough to write a concrete objective:
+1. Call `loopd_create_goal` with:
+   - `name` — a short slug (e.g. "pdf-notes")
+   - `objective` — a precise, self-contained statement including verification criteria
+   - `checks` — optional shell commands that must pass before the goal can be marked complete (e.g. `["npm test"]`)
+   - `progressFile` — optional path to a markdown progress file
+   - limits — optional `maxTurns`, `maxNoProgress`, `maxFailures`, `compactEvery`, `timeoutMs`
+2. After it returns, tell the user the goal is running in the background and they can monitor it with `/loop` (or Ctrl+L).
+
+Important: the worker session runs autonomously — do not try to do the goal's work in this chat. This chat only creates the goal.