# gwt

[日本語](README.ja.md)

gwt is a desktop control plane for agent-driven development. It brings coding
agents, project context, shared coordination, GitHub Issue-backed specs,
semantic search, and managed workflow automation into one native GUI and
browser-accessible workspace.

Git worktrees are the isolation substrate behind gwt. They let gwt materialize
safe per-task workspaces for agents, but the product flow starts from work,
Issues, SPECs, search, and Board context rather than from branch management.

## Why gwt

- **Agent workspace** — launch, resume, and monitor `Claude Code`, `Codex`,
  `Gemini`, `OpenCode`, `Copilot`, and custom agents from a shared canvas.
- **Shared Board** — keep user and agent communication in one repo-scoped
  timeline with `status`, `claim`, `next`, `blocked`, `handoff`, `decision`,
  and `question` posts.
- **Agent-to-agent coordination** — managed hooks remind agents to post
  reasoning milestones and inject recent Board context so parallel agents can
  see decisions, handoffs, blockers, and targeted requests.
- **Semantic Knowledge Bridge** — search Issues, SPECs, project source files,
  and docs through a ChromaDB / multilingual-e5 index instead of relying only
  on substring matches.
- **GitHub Issue-backed SPECs** — treat `gwt-spec` Issues as the source of
  truth while reading and editing sections through the local cache-backed CLI.
- **Managed workflow skills** — use bundled `gwt-*` skills for discussion,
  issue routing, planning, TDD implementation, PR work, architecture review,
  project search, and agent-pane management.
- **Operator canvas** — arrange Agent, Board, Issue, SPEC, Logs, Profile,
  File Tree, Branches, and PR surfaces in one mission-control style workspace.

## Install

Download the release asset for your platform from
[GitHub Releases](https://github.com/akiojin/gwt/releases).

### macOS

- GUI-first installer: `gwt-macos-universal.dmg`
- Open `GWT.app` from the mounted DMG for the native desktop launch surface
- Use the install script when you want the `gwt` and `gwtd` CLIs in your `PATH`

```bash
curl -fsSL https://raw.githubusercontent.com/akiojin/gwt/main/installers/macos/install.sh | bash
```

Install a specific version:

```bash
curl -fsSL https://raw.githubusercontent.com/akiojin/gwt/main/installers/macos/install.sh | bash -s -- --version <version>
```

### Windows

- GUI-first installer: `gwt-windows-x86_64.msi`
- Portable bundle: `gwt-windows-x86_64.zip`
- The public front door is `gwt.exe`; `gwtd.exe` is bundled for internal runtime use

### Linux

- Portable bundles:
  - `gwt-linux-x86_64.tar.gz`
  - `gwt-linux-aarch64.tar.gz`
- Extract `gwt` and `gwtd` into a directory on your `PATH`

### Uninstall (macOS)

```bash
curl -fsSL https://raw.githubusercontent.com/akiojin/gwt/main/installers/macos/uninstall.sh | bash
```

## Requirements

- `git` available in `PATH`
- `gh auth login` completed for GitHub-backed features
- AI provider credentials when you use agents:
  - `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`
  - `OPENAI_API_KEY`
  - `GOOGLE_API_KEY` or `GEMINI_API_KEY`
- Python 3.9+ when gwt needs to bootstrap or repair the shared project index runtime

Linux desktop builds also require WebKitGTK-related system packages. See
[docs/docker-usage.md](docs/docker-usage.md) for the dependency set used in CI.

## Usage

Launch the native GUI:

```bash
gwt
```

At startup you can restore the previous session or open a new project
directory. The app also starts a local HTTP/WebSocket server for the WebView
surface and prints a URL such as `http://127.0.0.1:<port>/` to stderr. You can
open that URL in a regular browser while the native app is running.

### Headless / Browser-only mode

`gwt serve` (equivalent alias: `gwt --headless`) launches the same UI without
opening a native window. The embedded HTTP / WebSocket server stays up and
the operator opens the printed URL in any browser instead.

```bash
gwt serve                              # 127.0.0.1, random port, auto-open browser
gwt serve --no-open                    # same, but suppress the browser launch (CI / scripts)
gwt serve --port 8787                  # fixed port + auto-open browser
gwt serve --bind 0.0.0.0 --port 8787   # share with the LAN (VPN-extended), auto-open browser
gwt --headless --port 8787             # same as `gwt serve --port 8787`
```

The system browser is opened automatically by default. Pass `--no-open` for
CI / automation use cases that only need the server running. `--open` is kept
as a no-op flag for backward compatibility with existing scripts.

Trust boundary: **LAN only** (including VPN-extended LAN). `gwt serve` does
not ship TLS termination, an authentication gate, or rate limiting. Anyone
that can reach the bind address can drive the embedded UI, which includes
spawning terminals. The `--bind` flag is opt-in: the default `127.0.0.1`
keeps the same loopback-trust behaviour as the native GUI. For external
access, run the host behind a VPN (Tailscale, WireGuard, etc.) rather than
exposing the port to the public Internet.

Platform note: on Linux, `tao 0.35` still requires a display server (X11 or
Wayland) at EventLoop creation, so v1 of `gwt serve` inherits the GUI's
`DISPLAY` dependency. macOS and Windows headless installs need nothing
special; Linux operators in pure-headless environments (no DISPLAY) should
either use `Xvfb`/`xvfb-run` or wait for the tao-detach follow-up tracked
under SPEC-1942.

Every HTTP / WebSocket request is mirrored to `tracing::info!(target =
"gwt_access", ...)` so the operator can see *which* peer is connecting in
real time on stderr and in `~/.gwt/logs/<date>/`. `/healthz` is demoted to
`debug!` to avoid drowning the stream with health probes.

Lifecycle: the `gwt serve` process owns the agent / PTY lifetime. Closing a
browser tab does **not** stop running agents — only `Ctrl-C` / `SIGTERM`
asks the server to drain PTYs and exit gracefully. The GUI and a headless
session for the same worktree are isolated by separate lock kinds, so you
can run `gwt` and `gwt serve` together; a startup warning surfaces the
co-existence so it is intentional, not accidental.

CLI subcommands run through `gwtd` without opening a GUI window:

```bash
gwtd issue spec 1784 --section plan
gwtd pr current
gwtd board show
gwtd hook workflow-policy
gwtd daemon status            # inspect the per-project runtime daemon
```

Managed hooks and runtime delegation use `gwtd`. On macOS and Linux,
running `gwtd daemon start` brings up a per-project runtime daemon
(Unix-domain socket IPC) that multi-instance event fan-out depends on
— for example, with the daemon running, Board posts you make in one
`gwt` window appear in another instance opened on the same repo
without a polling delay. The daemon keeps running in the background
until you stop it (Ctrl-C or SIGTERM). `gwtd daemon status` prints
the live endpoint for diagnostics. Without `gwtd daemon start`,
multi-instance fan-out is inactive but local file-based state and
the file watcher continue to work as before.

Windows currently has no long-running daemon: `gwtd daemon start`
exits with "not yet implemented", and managed hooks fall back to
synchronous `gwt hook ...` dispatch. Multi-instance fan-out is
therefore unavailable on Windows pending follow-up work; `gwtd
daemon status` still works there but always reports `stopped` until
the named-pipe path lands.

## Agent Workflow

1. Open a project directory, clone from GitHub, or restore the previous
   project.
2. Use `Board`, `Issue`, `SPEC`, and Knowledge search surfaces to understand
   the current work, related owners, and prior decisions.
3. Choose `Start Work` from the Project Bar or Command Palette when the task is
   still work-shaped rather than branch-shaped.
4. Launch an `Agent` from Start Work, or launch directly from an Issue/SPEC
   detail when the owner is already known.
5. Let gwt materialize the backing `work/YYYYMMDD-HHMM[-n]` branch/worktree
   only when launch is confirmed.
6. Use the shared Board for status, claims, next steps, blockers, handoffs,
   and decisions while agents run.
7. Open `Branches` only when you need Git inspection, filtering, cleanup, or
   lower-level branch/worktree details.

Common windows include:

- `Agent` — live coding-agent process windows created through Start Work or
  Launch Agent
- `Board` — shared user/agent timeline for reasoning and coordination
- `Issue` and `SPEC` — cache-backed Knowledge Bridge windows with semantic
  search, detail panes, and Launch Agent handoff
- `Logs` — project diagnostics and live log surface
- `Profile` — environment/profile management
- `File Tree` — live read-only repository tree
- `Branches` — branch inspection, filtering, cleanup, and Git details
- `Settings` — application and agent configuration. The `System` tab lets
  you choose the narrative output language (Auto / English / 日本語) used
  for Workspace summaries and Board post bodies. `Auto` resolves against
  the OS locale and falls back to English when the locale is `C` / `POSIX`
  or unavailable. The setting is global and persisted under `[ai].language`
  in `~/.gwt/config.toml`. UI labels stay English (see SPEC-1933 NFR-005).
- `PR` — pull-request workflow surface; detailed list support depends on the
  cache-backed PR source as it lands

`Agent` is the live process window for coding-agent sessions. `Board` is the
coordination surface agents use to expose status, decisions, handoffs, and
requests. `Issue` and `SPEC` use the local cache and semantic index rather than
rendering direct GitHub API responses in the frontend.

On Windows Host launches, Launch Agent lets you choose Command Prompt, Windows
PowerShell, or PowerShell 7. Docker launches continue to use the container
shell.

In terminal windows, drag to select text and release the mouse button to copy.
On Windows and Linux, `Ctrl+Shift+C` also copies the current terminal
selection. `Ctrl+C` stays mapped to the running terminal process.

## Knowledge, Search, and Managed Skills

gwt keeps project knowledge close to the agent workspace:

- `gwtd issue spec <n>` reads GitHub Issue-backed SPECs from the local cache.
- `gwtd issue view <n>` and `gwtd issue comments <n>` provide cache-backed Issue
  access through the gwt CLI surface.
- `gwt-search` searches SPECs, Issues, source files, and docs through the shared
  ChromaDB runtime. Missing indexes are built on demand, and the desktop app can
  repair the managed Python search runtime when needed.
- The Issue/SPEC Knowledge Bridge windows combine cache-backed list/detail views
  with semantic ranking, exact-match priority, and match percentages.

Bundled workflow skills are materialized into `.claude/skills`,
`.claude/commands`, and `.codex/skills` for the active worktree. The public
entrypoints are:

- `gwt-discussion` — investigation-first discussion and design clarification
- `gwt-register-issue` / `gwt-fix-issue` — issue intake and issue-driven fixes
- `gwt-plan-spec` — implementation planning for an approved SPEC
- `gwt-build-spec` — TDD-oriented implementation from an approved task
- `gwt-manage-pr` — PR create/check/fix lifecycle
- `gwt-arch-review` — architecture review and improvement routing
- `gwt-search` — unified semantic search
- `gwt-agent` — running agent-pane inspection and control

Managed hooks preserve user hooks while adding gwt runtime behavior for agent
state, workflow guardrails, Board reminders, discussion/plan/build Stop checks,
and coordination-event summaries.

When an agent is launched by gwt with a live GUI/browser backend, managed hooks
also enable the local hook-forward bridge. The bridge posts hook events only to
the loopback endpoint and bearer token that gwt injects for that session, then
fans them out through the existing live event stream. Sessions started outside
gwt do not receive that target and `gwt hook forward` remains a silent no-op;
stale targets, refused connections, validation errors, and delivery timeouts are
fail-open diagnostics and do not block agent tool calls.

## Workspace Foundation

For isolation and repeatable agent sessions, gwt can manage each project as a
**Nested Bare + Worktree** layout under your workspace directory:

```
<workspace>/<project>/
├── <project>.git/          # bare repository
├── develop/                # develop worktree (default working directory)
├── feature/<name>/         # additional worktrees by branch
└── .gwt/project.toml       # gwt-managed project metadata
```

`gwt` auto-creates this layout when you choose `Clone from GitHub...` from
either the Project Picker (shown when no tab is open) or the top toolbar's
`Open Project ▾` split-button dropdown (always reachable from an active
project). The clone modal accepts a GitHub HTTPS/SSH URL or lets you search
repositories through `gh search repos`, then asks for a destination parent
folder. The new project is created at `<parent>/<project>/`, with a bare
`<project>.git/` repository and an initial worktree on `develop` when it
exists, otherwise on the remote default branch.

Existing Normal Git repositories (`.git/` directly under the project
directory) are recognised so a migration to the Nested Bare + Worktree layout
can be run on demand. The migration safely backs up the original tree to
`.gwt-migration-backup/`, rebuilds the bare repo, recreates each worktree,
and rolls back automatically if any phase fails. Tracking work is captured in
[GitHub Issue #1934 (SPEC-1934)](https://github.com/akiojin/gwt/issues/1934).

To migrate an existing Normal Git project, open it from gwt's project
picker (or via `Reopen Recent`). gwt detects the layout and shows a
Migrate confirmation modal.

Choose **Migrate** to run the migration now. Progress is streamed phase by
phase (Validate -> Backup -> Bareify -> Worktrees -> Submodules -> Tracking ->
Cleanup -> Done). On success the project tab reloads onto the new branch
worktree without restarting the app.

## Canvas Operations

- Zoom the canvas with the on-screen zoom buttons
- Pan the canvas by dragging the background
- Use `Tile` to arrange windows on a grid
- Use `Stack` to cascade windows with overlap
- Use `Align` to arrange windows on a grid without changing their size
- Use `Cmd/Ctrl+Shift+Right` and `Cmd/Ctrl+Shift+Left` to cycle focus; the
  focused window is recentered

## Operator Design Language (SPEC-2356)

Starting with the Operator Design System update, gwt is themed as a single
mission-control surface with editorial-industrial typography (`Mona Sans` for
body, `Hubot Sans` condensed for display, `JetBrains Mono` for terminal /
counters). The default type scale is tuned for developer readability, so
terminal text, IDs, paths, counters, and dense work surfaces stay legible during
long sessions while display typography remains reserved for headings and chrome
labels. Every chrome surface — Project Bar, Sidebar Layers, Status Strip,
Command Palette, Hotkey Overlay, Drawer modals, floating windows — shares a
single token system that ships in two flagship themes:

- **Dark Operator** (Mission Control / carbon + neon) — the default, optimized
  for long sessions
- **Light Operator** (Drafting Table / bone + ink) — for bright environments

The active theme follows your OS `prefers-color-scheme`, but the **Theme**
control in the Project Bar lets you choose `auto`, `dark`, or `light`. The
choice is persisted in browser storage and survives restarts. xterm terminal
content stays on the Dark Operator palette with larger developer-readable font
metrics, while the terminal window chrome follows the overall theme.
`prefers-reduced-motion: reduce`
disables the Living Telemetry pulse rim, status strip ticking, and Mission
Briefing intro reveal so the UI stays usable in motion-sensitive environments.
`forced-colors: active` (Windows High Contrast / macOS Increase Contrast)
falls back to system colors so accessibility is preserved.

### Hotkeys

| Combo | Action |
| --- | --- |
| `⌘K` / `⌘P` | Open the Command Palette (fuzzy search over all surface actions) |
| `⌘B` | Focus the Board surface |
| `⌘G` | Focus the Git (Branches) surface |
| `⌘L` | Focus the Logs surface |
| `⌘?` | Toggle the Hotkey Overlay (cheat sheet) |
| `⌘\` | Collapse / expand the Sidebar Layers |
| `Esc` | Close any open palette / overlay / drawer / dropdown |

### Accessibility

Every modal dialog (Command Palette, Hotkey Overlay, branch cleanup,
worktree migration, launch wizard, Add Window) follows the WAI-ARIA
dialog convention: `role="dialog"` with an accessible name, `aria-modal`,
focus moves into the dialog on open and returns to the trigger on close,
Tab cycles within the dialog (no keyboard trap escape), and Escape
dismisses. Async loading stages signal `aria-busy="true"` so screen
readers track progress. Error regions use `role="alert"` for immediate
announcement. WCAG 2.1 AA contrast is asserted across every text /
surface combination in both themes.

## SPEC and Runtime Quick Reference

- SPEC source of truth: GitHub Issues labeled `gwt-spec`
- Local cache path:
  `~/.gwt/cache/issues/<repo-hash>/`
- Managed agent integration files:
  `.claude/settings.local.json` and `.codex/hooks.json`
- List available SPECs:

```bash
gwtd issue spec list
```

- Read a SPEC:

```bash
gwtd issue spec <number>
```

- Read one section:

```bash
gwtd issue spec <number> --section spec|plan|tasks
```

## Logs

- App logs:
  `~/.gwt/projects/<repo-hash>/logs/gwt.log.YYYY-MM-DD`
- Session state:
  `~/.gwt/session.json`
- Project workspace state:
  `~/.gwt/projects/<repo-hash>/workspace.json`

## Development

### Build

```bash
cargo build -p gwt --bin gwt --bin gwtd
```

### Run

```bash
cargo run -p gwt --bin gwt
```

### Build a macOS app bundle

```bash
cargo install cargo-bundle
cargo bundle -p gwt --format osx
```

### Test

```bash
cargo test -p gwt-core -p gwt --all-features
```

### Release Asset Contract

```bash
npm run test:release-assets
```

### Frontend Bundle Contract

```bash
npm run test:frontend-bundle
```

### Release Flow Checks

```bash
npm run test:release-flow
```

### Lint

```bash
cargo clippy --all-targets --all-features -- -D warnings
```

### Format

```bash
cargo fmt
```

## Project Structure

```text
├── Cargo.toml          # Workspace configuration
├── crates/
│   ├── gwt/            # Desktop GUI + WebView server + CLI dispatch
│   ├── gwt-core/       # Core library
│   └── gwt-github/     # GitHub Issue SPEC cache / update layer
└── package.json        # npm package metadata and postinstall
```

## Specs

Detailed requirements live in GitHub Issues labeled `gwt-spec`. Use
`gwtd issue spec <n>` to inspect them locally through the cache-backed CLI.

## License

MIT
