Coduck is a local-first workspace for managing AI coding assistant chats across projects. It helps you find chats by the directory they belong to, reopen them in embedded terminal tabs, browse nearby files, and keep multiple conversations visible while you work.

The app currently supports Codex CLI sessions. Claude Code and Gemini CLI are shown as provider slots, but their adapters are not implemented yet.

• Indexes local Codex session files from CODEX_HOME or ~/.codex.
• Groups chats by their working directory so project conversations stay together.
• Opens Codex chats in embedded terminal tabs using codex resume.
• Supports multiple terminal tabs, draggable tab ordering, and a two-pane split workspace.
• Lets you create new Codex chats and plain terminal tabs in the selected directory.
• Lets you fork Codex chats into separate branches.
• Supports archive/unarchive actions for Codex sessions.
• Browses real folders and files, including files in directories that do not have chats.
• Previews text/code, images, PDFs, audio, video, and binary file metadata.
• Restores open tabs, split panes, selected directory, filters, and collapsed panels on relaunch.
• Runs locally through a Node API server; the browser never reads your filesystem directly.

Coduck is for developers who use AI coding assistants across multiple repositories and want a project-oriented way to find, continue, split, and organize their chats without hunting through separate app surfaces.

• Node.js and npm
• Codex CLI for live Codex terminal sessions
• A local Codex session store, usually ~/.codex

The app has been built and smoke-tested on Windows and in a Linux environment. macOS should work through the same POSIX path handling, but it has not been manually tested yet.

Install dependencies:

npm install

Start the local API and web app:

npm run dev

Open:

http://127.0.0.1:5174

The dev command starts:

• Web app: http://127.0.0.1:5174
• API server: http://127.0.0.1:4317

On Windows PowerShell, use npm.cmd if script execution policy blocks npm:

npm.cmd install
npm.cmd run dev

CODEX_HOME can point to a non-default Codex config/session directory. If it is not set, Coduck uses ~/.codex.

CODEX_HOME=/path/to/.codex npm run dev

CODEX_BIN can point to a specific Codex executable. If it is not set, Coduck resolves codex from your shell path.

CODEX_BIN=/path/to/codex npm run dev

Select a folder in the left sidebar to see chats whose working directory matches that folder. Selecting a drive or filesystem root shows chats under that root. Opening a file shows it in a tab. Opening a chat starts an embedded terminal tab for that session.

The terminal workspace supports:

• Multiple tabs
• Drag-and-drop tab ordering
• Two-pane split view
• Moving tabs between panes
• Per-tab color labels
• Hidden/reopenable details panel

When you switch to a chat tab, the selected directory follows that chat's working directory.

For an existing Codex chat, Coduck starts a WebSocket-backed PTY and runs:

codex resume --no-alt-screen --all -C <cwd> <sessionId>

A chat can be continued only when Codex CLI can resume the saved local session id. Restored tabs after a full app/server restart start fresh terminal processes; the old live PTY process itself is not preserved.

While the app is running, Swagger-style API docs are available at:

http://127.0.0.1:5174/api/docs

The raw OpenAPI document is available at:

http://127.0.0.1:5174/api/openapi.json

If the dev server is running in the current terminal, press:

Ctrl+C

If it was started in the background, stop the processes listening on the app ports.

Windows PowerShell:

Get-NetTCPConnection -LocalPort 5174,4317 -State Listen | Select-Object LocalPort,OwningProcess
Stop-Process -Id <PID1>,<PID2>

macOS/Linux:

lsof -ti :5174 :4317 | xargs kill

server/
  providers/          Provider registry and Codex adapter
  lib/                Shared server utilities
src/
  components/         Directory, session, file, and terminal UI
  core/               Shared app types and mock fallback data
  services/           Browser API client
  styles/             Theme and layout CSS
docs/
  architecture.md     Provider/API design
  api.md              Local HTTP and WebSocket API reference
  design.md           UX and visual design notes
  codex-provider.md   Codex discovery and parsing assumptions

Coduck is designed to run locally on 127.0.0.1. It reads local session files and filesystem metadata through the local API server. Do not expose the API server publicly.

Coduck is early-stage software. The Codex provider is the active implementation. Claude Code and Gemini CLI support are planned but not available yet.