Github - CLI Agents integration

[dzianisv]

Let's work on the universal integration with github for any cli agent.
All the agents now have a cli, that could run one-shot tasks.
Like opencode run, claude, codex, kilo, gemini cli, github co-pilot cli.
The point is to be able to assign locally running coding agent to the task, when is done, it has to git clone or git worktree if repo is presented, than start to work on the task. When completed, create a PR, and the service has to push github comment on the issue with thinking, progress, intermediate results.

Kind of github co-pilot or codex in cloud, but that could be easily runnable on localhost.

2/ If use follow up with comment on github, the service has to create a new instance of agent to continue running on the issue.

3/ Create a design of such solution. Research web well and github for altternatives. probalby there is something and we shouldn't re:invenet a wheel?

4/ If not available, design a solution end to end. Make it simple so it could be easially installed throug npm / bun on localhost and run as a systemd or launchd service.

5/ Implement and test on a simple PR.

6/ Make sure that if I follow up on github comments, it replies / spawns a new session.

7/ For now focus just on on opencode integration. Use opencode sdk.

[dzianisv]

This is a compelling vision. While tools like OpenHands (formerly OpenDevin) or Sweep.ai offer GitHub-to-Agent workflows, they often require complex Docker setups or are built as self-contained platforms rather than a lightweight "bridge" for existing CLI tools.

There is currently no universal, lightweight localhost bridge designed specifically to wrap any CLI agent (Claude, OpenCode, Kilo) and expose it as a GitHub worker.

---

1. Research & Alternatives

Before building, we should look at the "wheels" that already exist:

• OpenCode GitHub Action: OpenCode already has an official action (anomalyco/opencode/github). However, it runs on GitHub-hosted runners, not your localhost.
• Plandex / Sweep: These are "managed" agents. They own the workflow. They don't easily allow you to swap the "brain" for a local gemini-cli or claude instance.
• Goose (Block): A newer agent that has an MCP (Model Context Protocol) focus, but doesn't have a built-in "Local-to-GitHub Issue" daemon.

Verdict: There is a gap for a "Local Agent Gateway" (LAG)—a service that sits on your machine, listens to your repos, and spawns whichever CLI agent you prefer.

---

2. The Spec: "AgentBridge"

The goal is a simple Node/Bun service that acts as a Webhook-to-CLI orchestrator.

Core Requirements

• Webhook Proxy: Since localhost isn't public, use a built-in smee-client or ngrok wrapper to receive GitHub events.
• Worktree Isolation: Use git worktree to allow the agent to work on multiple issues simultaneously without messing up your main branch.
• Streaming Logs: Capture stdout and periodically post "Thinking..." updates to the GitHub issue.
• Session Management: Map GitHub Issue IDs to local Agent Session IDs to allow "Follow-up" comments.

---

3. Design: End-to-End Architecture

Components

1. Bridge Server (Node.js/Bun): A small Fastify/Express server.
2. Provider Wrapper: A generic interface to call agents.

• Example: opencode run "{prompt}" or claude "{prompt}".

3. State Store: A local SQLite or JSON file to map Issue_ID -> Branch_Name -> Session_ID.
4. GitHub Client: (Octokit) to handle comments and PR creation.

Workflow

1. Trigger: User comments @local-agent fix this on a GitHub Issue.
2. Ingress: Webhook hits the Bridge via a Smee tunnel.
3. Environment: Bridge creates git worktree add ../agent-task-123 feature/fix-issue-123.
4. Execution: Bridge calls opencode run inside that directory.
5. Feedback: Bridge scrapes logs and updates the GitHub comment every 30 seconds.
6. Completion: Once the process exits, Bridge runs git push and opens a PR.

---

4. Implementation (OpenCode Focus)

You can build this using the @opencode-ai/sdk for deep integration, or the CLI for simplicity. Below is the strategy for the AgentBridge using the OpenCode SDK.

Project Structure

agent-bridge/
├── src/
│   ├── index.ts        # Server & Webhook Logic
│   ├── git.ts          # Worktree & PR management
│   └── agents/
│       └── opencode.ts # OpenCode SDK integration
├── config.yaml         # Map @mentions to CLI commands
└── package.json

The "Follow-up" Logic

To ensure follow-up comments work, we must persist the sessionId.

// Example Logic in agents/opencode.ts
import { createOpencodeClient } from "@opencode-ai/sdk";

async function handleFollowUp(issueId: string, newComment: string) {
  const sessionId = db.get(issueId).sessionId;
  const client = createOpencodeClient({ baseUrl: "http://localhost:4096" });
  
  // Resume the existing session rather than starting over
  await client.session.prompt({
    path: sessionId,
    body: { prompt: newComment }
  });
}

---

5. Setup & Installation

To make it "simple" as requested, we package it as a global CLI.

1. Install: npm install -g agent-bridge
2. Configure: agent-bridge init (asks for GitHub Token and Smee URL).
3. Run as Service:

• macOS: agent-bridge service install (generates a launchd plist).
• Linux: agent-bridge service install (generates a systemd unit).

# Example command to start listening
agent-bridge start --proxy https://smee.io/your-unique-id

---

6. Testing on a Simple PR

1. Target: Create an issue: "Add a README.md description about the license."
2. Comment: @local-agent opencode fix this.
3. Observation: * The service clones/worktrees.

• OpenCode generates the text.
• Service creates a PR titled Agent: Fix License Description.
• You comment "Make it more professional."
• Service sees the comment, resumes the session, and updates the PR.

Would you like me to draft the actual package.json and the core index.ts file using the OpenCode SDK to get you started?

[dzianisv]

1. Competitive Landscape & "The Missing Wheel"

Tool | Focus | Localhost Service? | Multi-Agent Support? -- | -- | -- | -- OpenCode GitHub App | Cloud-first | No (runs on GH Actions) | No (OpenCode only) agenttools/worktree | Worktree management | CLI-only | No (Claude Code only) Kwaak | Parallel agents | CLI-only | Internal agents only Formic | Orchestration | Yes (Docker) | Yes (Claude/Copilot) Proposed: LAG | Bridge/Gateway | Yes (Systemd/Launchd) | Universal (Any CLI)

The "Wheel" to Build: A lightweight Local Agent Gateway (LAG). It acts as a headless orchestrator that manages git worktree lifecycles and maps GitHub issue comments to local agent sessions using the OpenCode SDK.

---

2. Technical Specification: LAG (Local Agent Gateway)

Core Architecture

• Ingress: A smee-client or ngrok wrapper to receive Webhooks without port forwarding.

• Controller: A Node.js/Bun service that parses /command triggers.

• Isolation: Uses git worktree for every new issue to prevent workspace pollution.

• Session State: A local SQLite database mapping GitHub_Issue_ID to OpenCode_Session_ID.

The OpenCode Integration (SDK)

Instead of just spawning a shell, we will use the @opencode-ai/sdk to:

1. Initialize: Create a headless session in a specific directory (the worktree).

2. Streaming: Capture the thought and action events from the SDK to post real-time "thinking" updates to GitHub.

3. Persistence: Store the sessionId to resume the conversation when a user follows up on GitHub.

---

3. System Design

Deployment Diagram

Plaintext

[ GitHub ] <--- Webhook (Issue Comment) ---> [ Smee.io Tunnel ]
                                                    |
                                            [ Localhost LAG Service ]
                                                    |
                    -----------------------------------------------------------------
                    |                               |                               |
          [ SQLite State Store ]          [ Git Worktree Manager ]        [ OpenCode SDK Client ]
          (Issue # -> SessionID)          (Clones/Branches per task)      (The "Brain" on Port 4096)

---

4. Implementation Strategy (Local Setup)

Step 1: Install & Boot

Bash

# Install the gateway
npm install -g local-agent-gateway
# Start the local OpenCode server (headless mode)

opencode serve --port 4096

Step 2: The Gateway Logic (Simplified)

The gateway will monitor the webhook for a specific pattern, e.g., @local fix this.

TypeScript

import { OpencodeClient } from "@opencode-ai/sdk";

import { Octokit } from "@octokit/rest";

const client = new OpencodeClient({ baseUrl: "http://localhost:4096" });
async function onIssueComment(payload) {

const { issue, comment, repository } = payload;
// 1. Check if we have an existing session for this issue

let session = await db.get(issue.id);
if (!session) {

// 2. New Task: Setup Worktree

const worktreePath = ./worktrees/issue-<span class="hljs-subst" style="font-family: &quot;Google Sans Text&quot;, sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">${issue.<span class="hljs-built_in" style="font-family: &quot;Google Sans Text&quot;, sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">number</span>}</span>;

await git.createWorktree(repository.url, worktreePath, fix/issue-<span class="hljs-subst" style="font-family: &quot;Google Sans Text&quot;, sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">${issue.<span class="hljs-built_in" style="font-family: &quot;Google Sans Text&quot;, sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">number</span>}</span>);
<span class="hljs-comment" style="font-family: &quot;Google Sans Text&quot;, sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">// 3. Start OpenCode Session</span>
session = <span class="hljs-keyword" style="font-family: &quot;Google Sans Text&quot;, sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">await</span> client.createSession({ <span class="hljs-attr" style="font-family: &quot;Google Sans Text&quot;, sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">path</span>: worktreePath });
<span class="hljs-keyword" style="font-family: &quot;Google Sans Text&quot;, sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">await</span> db.save(issue.id, session.id);

}
// 4. Send Prompt & Stream back to GH

const stream = await client.prompt(session.id, comment.body);

for await (const chunk of stream) {

if (chunk.type === 'thought') {

await updateGithubComment(issue.id, Agent is thinking: <span class="hljs-subst" style="font-family: &quot;Google Sans Text&quot;, sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">${chunk.text}</span>);

}

}

}

---

5. Service Configuration

For macOS (launchd)

Create ~/Library/LaunchAgents/com.lag.plist:

For Linux (systemd)

Create /etc/systemd/system/lag.service:

Ini, TOML

[Service]

ExecStart=/usr/bin/lag start --config /home/user/.lag.yaml

Restart=always

User=youruser

---

6. Testing the Integration

1. Action: Go to your GitHub repo and open an issue.

2. Comment: @local fix the typo in the license file.

3. Observation:

   • LAG detects the webhook.

   • LAG runs git worktree add ../issue-1 fix/issue-1.

   • OpenCode SDK starts a session in that folder.

   • A PR is automatically opened by the service once OpenCode exits with a "success" status.

4. Follow-up: Comment on the PR: "Actually, change the year to 2026."

5. Observation: LAG retrieves the sessionId, sends the update to OpenCode, and OpenCode pushes a second commit to the same branch.

Would you like me to generate the full index.ts and package.json code for this "LAG" bridge now?