Merge pull request #1 from bgrgicak/add-opencode-agent

Add opencode as a second agent

Author: bgrgicak

.github/workflows/ci.yml

@@ -28,6 +28,10 @@ jobs:
         run: npm test
       - name: E2E tests (sessions)
         run: npx tsx --test 'packages/cli/test/e2e/sessions.e2e.ts'
+      - name: Install opencode
+        run: npm install -g opencode-ai
+      - name: E2E tests (opencode)
+        run: npx tsx --test 'packages/cli/test/e2e/opencode.e2e.ts'
 
   e2e-docker:
     runs-on: ubuntu-latest

README.md

@@ -1,6 +1,6 @@
 # flout
 
-Manage persistent AI agent sessions with tmux. Start, stop, join, and restart long-running Claude Code sessions from the command line — locally or in container sandboxes (Docker, Podman, or containerd via Colima).
+Manage persistent AI agent sessions with tmux. Start, stop, join, and restart long-running coding-agent sessions (Claude Code or opencode) from the command line — locally or in container sandboxes (Docker, Podman, or containerd via Colima).
 
 ## Install
 
@@ -35,6 +35,17 @@ flout join myproject     # reattach after disconnecting
 flout stop myproject     # tear it down
 ```
 
+### Choosing an agent
+
+flout defaults to Claude Code. Pass `--agent opencode` (or set `FLOUT_AGENT=opencode`) to use [opencode](https://opencode.ai) instead. opencode does not have a remote-control mode, so `flout remote` and `flout restart` only work with Claude.
+
+```bash
+flout setup --agent opencode             # one-time setup for opencode
+flout start myproject --agent opencode   # start an opencode session
+```
+
+opencode ships with built-in models that work without an API key, so `flout status --agent opencode` is happy as soon as the `opencode` binary is on your `PATH`. Run `opencode auth login` only if you want to register additional providers.
+
 ### Remote sessions
 
 Remote sessions auto-restart if the agent exits, so they stay running unattended.

package-lock.json

@@ -15,6 +15,9 @@ packages/
   claude/             @flout/claude — Claude Code provider
     src/index.ts      Claude-specific commands, auth, and trust checking
 
+  opencode/           @flout/opencode — opencode provider (no remote-control mode)
+    src/index.ts      opencode-specific commands and auth checking
+
   sandbox/            @flout/sandbox — Multi-engine container sandbox
     src/engine.ts     Engine detection (Docker, Podman, nerdctl) and abstraction
     src/colima.ts     Colima VM lifecycle management
@@ -35,22 +38,24 @@ interface Agent {
   name: string;
   binary: string;
   installHint?: string;
-  remoteCommand(sessionName: string): string;
+  remoteCommand?(sessionName: string): string;     // optional — omit if no remote-control mode
   startCommand(): string;
   loginCommand(): string;
-  setupTokenCommand(): string;
+  setupTokenCommand?(): string;                    // optional — omit if login is sufficient
   isAuthenticated(): boolean;
   isTrusted(dir: string): boolean;
   trustCommand(): string;
   encodePath(dir: string): string;
 }
 ```
 
+`remoteCommand` and `setupTokenCommand` are optional. When `remoteCommand` is missing, `flout remote` and `flout restart` exit with an error for that agent.
+
 ## Adding a new agent
 
 1. Create a new package `packages/<name>/` with `src/index.ts` exporting an object satisfying `Agent`
-2. Add it as a workspace dependency in `packages/cli/package.json`
-3. Wire it up in `packages/cli/src/cli.ts`
+2. Add it as a workspace dependency in `packages/cli/package.json` and a tsconfig reference in `packages/cli/tsconfig.json` and the root `tsconfig.json`
+3. Register it in the `AGENTS` map in `packages/cli/src/cli.ts` so it can be selected via `--agent <name>` (or `FLOUT_AGENT=<name>`)
 
 ## Container sandbox
 
@@ -76,6 +81,16 @@ npm test        # runs tests across all workspaces
 
 Tests use `node:test` and `node:assert`. Integration tests use a real bash-based agent and real tmux sessions — no mocks.
 
+### E2E tests
+
+E2E suites live in `packages/cli/test/e2e/` and run real flout commands end-to-end:
+
+- `sessions.e2e.ts` — exercises the Claude path. Uses `@flout/claude-mock-api` (HTTP mock) and a fake `claude` binary that just sleeps, so the suite needs no external services.
+- `opencode.e2e.ts` — exercises the opencode path. Runs the **real** `opencode` binary (no mock), since opencode ships with built-in models that work without any external API key. The suite skips itself when `opencode` is not in `PATH`, so local devs don't have to install it.
+- `sandbox.e2e.ts` / `sandbox-engines.e2e.ts` / `docker.e2e.ts` — container-engine integration.
+
+Run a single suite with `npx tsx --test packages/cli/test/e2e/<file>.e2e.ts`. CI installs opencode via `npm i -g opencode-ai` and runs the opencode suite as part of the standard build-lint-test job.
+
 ## Constraints
 
 - Minimal dependencies — only TypeScript and @types/node as dev deps

packages/cli/AGENTS.md

@@ -38,6 +38,7 @@
   "dependencies": {
     "@flout/claude": "*",
     "@flout/docker": "*",
+    "@flout/opencode": "*",
     "@flout/sandbox": "*"
   },
   "engines": {

packages/cli/package.json

@@ -1,22 +1,36 @@
 import path from 'path';
 import claude from '@flout/claude';
+import opencode from '@flout/opencode';
 import * as docker from '@flout/docker';
 import * as sandbox from '@flout/sandbox';
 import { normalizeEngine } from '@flout/sandbox';
 import * as sessions from './sessions.js';
 import { setup, trust } from './setup.js';
 import type { Agent } from './types.js';
 
-const agent: Agent = claude;
+const AGENTS: Record<string, Agent> = { claude, opencode };
+
 const args = process.argv.slice(2);
-const command = args[0];
 
 function getFlag(flag: string): string | null {
   const idx = args.indexOf(flag);
   if (idx === -1 || idx + 1 >= args.length) return null;
   return args[idx + 1];
 }
 
+function resolveAgent(): Agent {
+  const name = getFlag('--agent') || process.env.FLOUT_AGENT || 'claude';
+  const a = AGENTS[name];
+  if (!a) {
+    console.error(`Unknown agent '${name}'. Available: ${Object.keys(AGENTS).join(', ')}`);
+    process.exit(1);
+  }
+  return a;
+}
+
+const agent: Agent = resolveAgent();
+const command = args[0];
+
 function getPassthroughArgs(): string[] {
   const idx = args.indexOf('--');
   if (idx === -1) return [];
@@ -44,8 +58,12 @@ Usage:
   flout trust <dir>                    Trust a project directory
   flout sandbox <cmd> [<name|id>]      Manage container sandboxes (start|stop|shell|claude|status)
 
+Global flags:
+  --agent <claude|opencode>            Pick the agent (default: claude, or $FLOUT_AGENT)
+
 Session names are optional for start/remote (defaults to directory basename).
-When multiple sessions share a name, use the full ID shown by flout list.`);
+When multiple sessions share a name, use the full ID shown by flout list.
+Note: 'remote' and 'restart' require an agent that supports remote-control mode.`);
 }
 
 switch (command) {

packages/cli/src/cli.ts

@@ -73,6 +73,10 @@ export function start(label: string, dir: string, agent: Agent): string {
 }
 
 export function remote(label: string, dir: string, agent: Agent): string {
+  if (!agent.remoteCommand) {
+    console.error(`Agent '${agent.name}' does not support remote-control sessions.`);
+    process.exit(1);
+  }
   const resolved = path.resolve(dir);
   if (!fs.existsSync(resolved)) {
     console.error(`Error: directory '${resolved}' does not exist`);
@@ -130,6 +134,10 @@ export function list(): void {
 }
 
 export function restart(query: string, dir: string, agent: Agent): string {
+  if (!agent.remoteCommand) {
+    console.error(`Agent '${agent.name}' does not support remote-control sessions.`);
+    process.exit(1);
+  }
   const session = resolveSession(query);
   spawnSync('tmux', ['kill-session', '-t', session]);
   const label = session.replace(/^flout-\d{4}-\d{6}-/, '');
@@ -138,8 +146,10 @@ export function restart(query: string, dir: string, agent: Agent): string {
 
 export function status(agent: Agent): void {
   if (!agent.isAuthenticated()) {
-    console.log('Not logged in. Run: claude');
-    console.log('Go through the setup process, then run: flout remote claude');
+    console.log(`Not logged in. Run: ${agent.loginCommand()}`);
+    if (agent.remoteCommand) {
+      console.log(`Go through the setup process, then run: flout remote ${agent.name}`);
+    }
     return;
   }
   list();

packages/cli/src/sessions.ts

@@ -59,11 +59,13 @@ export function setup(agent: Agent): void {
     process.exit(1);
   }
 
-  console.log('\nSetting up long-lived token...');
-  const token = spawnSync(agent.setupTokenCommand(), { stdio: 'inherit', shell: true });
-  if (token.status !== 0) {
-    console.error('Token setup failed.');
-    process.exit(1);
+  if (agent.setupTokenCommand) {
+    console.log('\nSetting up long-lived token...');
+    const token = spawnSync(agent.setupTokenCommand(), { stdio: 'inherit', shell: true });
+    if (token.status !== 0) {
+      console.error('Token setup failed.');
+      process.exit(1);
+    }
   }
 
   console.log('\nSetup complete.');

packages/cli/src/setup.ts

@@ -2,10 +2,12 @@ export interface Agent {
   name: string;
   binary: string;
   installHint?: string;
-  remoteCommand(sessionName: string): string;
+  /** Long-running remote-control mode. Omit if the agent has no equivalent. */
+  remoteCommand?(sessionName: string): string;
   startCommand(): string;
   loginCommand(): string;
-  setupTokenCommand(): string;
+  /** Optional long-lived token setup step run after login. */
+  setupTokenCommand?(): string;
   isAuthenticated(): boolean;
   isTrusted(dir: string): boolean;
   trustCommand(): string;

packages/cli/src/types.ts

@@ -89,4 +89,28 @@ describe('CLI', () => {
     assert.ok(stdout.includes('start [name]'));
     assert.ok(stdout.includes('remote [name]'));
   });
+
+  it('lists --agent flag in help', () => {
+    const { stdout } = run('--help');
+    assert.ok(stdout.includes('--agent'));
+    assert.ok(stdout.includes('opencode'));
+  });
+
+  it('exits 1 on unknown --agent value', () => {
+    const { stderr, exitCode } = run('status', '--agent', 'nonexistent');
+    assert.strictEqual(exitCode, 1);
+    assert.ok(stderr.includes('Unknown agent'));
+  });
+
+  it('errors on remote when agent does not support it (opencode)', () => {
+    const { stderr, exitCode } = run('remote', 'demo', '--agent', 'opencode');
+    assert.strictEqual(exitCode, 1);
+    assert.ok(stderr.includes('does not support remote-control'));
+  });
+
+  it('errors on restart when agent does not support remote-control (opencode)', () => {
+    const { stderr, exitCode } = run('restart', 'anything', '--agent', 'opencode');
+    assert.strictEqual(exitCode, 1);
+    assert.ok(stderr.includes('does not support remote-control'));
+  });
 });