# OpenCode Web

Dockerized [OpenCode](https://opencode.ai) with [OpenChamber](https://github.com/openchamber/openchamber) as the browser/PWA frontend.

## What it does

This project runs OpenChamber in the container and lets OpenChamber start and keep OpenCode available in the background.

The stack inside the container:

- **OpenCode CLI** — the AI coding assistant
- **OpenChamber** — web frontend that starts and presents OpenCode
- **Node 26** — runtime
- **Graphifyy** — knowledge-graph skill for codebase understanding (installed via pipx)

## OpenCode configuration

The `opencode-config/` directory contains a full custom OpenCode agent setup, mounted at `/home/node/.config/opencode` inside the container.

### Agents

| File | Mode | Purpose |
| --- | --- | --- |
| `agents/build.md` | primary | Default agent with full permission set for implementation work |
| `agents/explore.md` | subagent | Specialized codebase file/content search |
| `agents/general.md` | subagent | General-purpose multi-step research and execution |
| `agents/plan.md` | primary | Plan mode — architecture design and implementation plans (read-only) |
| `agent/executor.md` | subagent | Runs shell commands only, no editing or file-reading |

### Commands

| File | Description |
| --- | --- |
| `command/commit.md` | Create git commits with auto-generated conventional commit messages |
| `command/rapid.md` | Fast iteration mode — quick fixes without extensive planning |
| `commands/plan.md` | Creates detailed implementation plans |
| `commands/review.md` | Reviews code changes (commit, branch, PR, or uncommitted) |

### Plugins

| File | Description |
| --- | --- |
| `plugin/fail-fast.ts` | Converts denied permissions and missing shell utilities into explicit task failures so agents don't stall or retry blocked actions |

### Snippets

| File | Aliases | Description |
| --- | --- | --- |
| `snippet/commit-message.md` | `cm` | Generates a commit message from current changes |
| `snippet/create-plan.md` | `plan` | Creates an implementation plan from the current session |

### Permissions

Fine-grained tool permissions are defined in `opencode.jsonc` (auto-generated, gitignored). Each agent has a tailored permission set — for example, `explore` has broad read/search access with bash allowed, while `build` has write/edit access but denies bash for safety.

## Fail-fast plugin

The fail-fast plugin (`plugin/fail-fast.ts`) hooks into OpenCode's tool lifecycle to catch three conditions:

1. **Permission denied** — if a `permission.ask` results in `deny`, the plugin throws a `FAIL_FAST_PERMISSION_DENIED` error with the permission name and next-action guidance.
2. **Invalid command** — if bash is called without a command, it throws `FAIL_FAST_INVALID_COMMAND`.
3. **Missing utility** — after every bash execution, the plugin checks stderr/stdout for "command not found", "not found", "ENOENT" patterns. If found, it throws `FAIL_FAST_MISSING_UTILITY` with the utility name.

This prevents agents from silently retrying blocked operations or looping on missing dependencies.

## How to run

```bash
docker compose up -d
```

Open `http://localhost:5200` in your browser.

To run OpenChamber on a different port, set `OPENCHAMBER_PORT` in `.env` and restart the container:

```env
OPENCHAMBER_PORT=5300
```

The container uses host networking, so OpenChamber binds directly to `OPENCHAMBER_PORT`; there is no separate Docker port mapping to update.

To protect the UI, set `UI_PASSWORD` in `.env`.

User and group IDs can be set in `.env` to match the host user:

```env
UID=1000
GID=1000
```

## How to update

Rebuild the image to pull the latest versions of OpenCode and OpenChamber:

```bash
docker compose build --no-cache
docker compose up -d
```

## Managing repositories

Set `REPOSITORIES_PATH` in `.env` to the host directory that contains repositories OpenCode should work on:

```env
REPOSITORIES_PATH=./repositories
```

The directory is mounted at `/home/repositories` inside the container.

## Container details

| Aspect | Detail |
| --- | --- |
| Network | `host` mode — no port mapping needed |
| Docker access | `/var/run/docker.sock` mounted for in-container Docker usage |
| Container user | Runs as `${UID}:${GID}` (default 1000:1000) |
| OpenChamber | Configured to allow unauthenticated LAN access (`OPENCHAMBER_ALLOW_UNAUTHENTICATED_LAN=true`) |

## Persisted data (gitignored)

| Local path | Container mount point | Purpose |
| --- | --- | --- |
| `.config/opencode-data/` | `/home/node/.local/share/opencode` | Agent state and tool outputs |
| `.config/opencode-state/` | `/home/node/.local/state/opencode` | Session and runtime state |
| `.config/opencode-cache/` | `/home/node/.cache/opencode` | Model cache and temporary data |
| `.config/openchamber-config/` | `/home/node/.config/openchamber` | OpenChamber configuration and session data |

## Browser and PWA notifications

OpenChamber can send browser notifications for prompt completion, questions, errors, and subtasks.

To receive notifications, open OpenChamber in your browser or installed PWA and allow notifications for the site/app when prompted. If notifications were previously blocked, reset the site notification permission in your browser settings.