kuannnn
42861ea7fa
Multi-adapter mobile UI for AI coding assistants. Supports Claude Code, Codex CLI, and Gemini CLI through one interface. Features: - Real-time bidirectional sync via tmux + WebSocket - Cross-AI review (send one AI's output to another for review) - Multi-review tabs with minimize/expand - Push notifications (PWA) with smart session-aware filtering - Three-channel event system (hooks, file watcher, pane monitor) - Voice input, image paste, draft persistence - Terminal-native design (JetBrains Mono, dark theme, pixel art claw) - CLI with --adapter flag on every command - Zero-overhead fire-and-forget hooks
257 lines
10 KiB
Markdown
257 lines
10 KiB
Markdown
# Session ID Unification Design Spec
|
|
|
|
## Problem
|
|
|
|
CodeTap's session management has grown organically and now has several issues:
|
|
|
|
1. **Dual ID system** — Each session has an "internal ID" (`session-{timestamp}` or `desktop-{uuid前8字}`) and a "CLI UUID". The internal ID is meaningless to users but is what the UI displays.
|
|
2. **Dual storage** — `session-map.json` (file) and SQLite (DB) both store session mappings. The file is written by the SessionStart hook but only read on server startup, causing `codetap new` sessions to not appear in Active Sessions until server restart.
|
|
3. **`desktop-` prefix confusion** — Sessions that are "rediscovered" after a non-graceful server restart get a new `desktop-` internal ID, losing their original ID.
|
|
4. **No adapter awareness in IDs** — Internal IDs don't indicate which adapter (Claude/Codex/Gemini) the session belongs to.
|
|
5. **User can't resume from desktop** — The chat header shows the internal ID which can't be used with `claude --resume`.
|
|
|
|
## Design Decisions
|
|
|
|
| Topic | Decision |
|
|
|-------|----------|
|
|
| Scope | All adapters (Claude, Codex, future) |
|
|
| Storage | SQLite only — remove session-map.json |
|
|
| SessionStart hook | POST to server API (like all other hooks) |
|
|
| Internal ID format | `{adapter}-{timestamp}` (e.g., `claude-1774210269126`) |
|
|
| `desktop-` prefix | Removed entirely |
|
|
| Non-graceful restart recovery | Read original internal ID from DB |
|
|
| User-facing display | Chat header: CLI UUID (primary) + internal ID (secondary) |
|
|
| Active Sessions list | Keep showing `firstPrompt` (no change) |
|
|
| DB on shutdown | Clear `sessions` table (tmux windows are killed, records are useless) |
|
|
| CLI `--adapter` flag | Added to `codetap new` and `codetap --continue` |
|
|
| CLI `--resume` | Accepts internal ID or CLI UUID; scans JSONL dirs to detect adapter |
|
|
| CLI `--continue` | Pass through to adapter CLI's native continue command |
|
|
| Adapter selector UI | Not in scope (future work) |
|
|
|
|
## Architecture
|
|
|
|
### Internal ID Format
|
|
|
|
```
|
|
{adapter}-{timestamp}
|
|
|
|
Examples:
|
|
claude-1774210269126
|
|
codex-1774210345678
|
|
gemini-1774210500000
|
|
```
|
|
|
|
Produced by:
|
|
- `startSession()` in each adapter (Web UI new session)
|
|
- `bin/codetap` CLI script (`codetap new`, `codetap --resume`, `codetap --continue`)
|
|
|
|
### Single Source of Truth: SQLite
|
|
|
|
All session mappings go through SQLite. No file-based storage.
|
|
|
|
**SessionStart hook flow (unified for all entry points):**
|
|
|
|
```
|
|
Claude/Codex CLI starts → SessionStart hook fires
|
|
↓
|
|
POST /api/hooks/{adapter}/session-start
|
|
body: { session_id: "<CLI UUID>", cwd: "/path", ... }
|
|
↓
|
|
Server handler:
|
|
1. Find tmux window for this session (by window name or DB lookup)
|
|
2. If session already in memory → update mapping (e.g., /resume changed UUID)
|
|
3. If session NOT in memory → create new entry:
|
|
- Internal ID from tmux window name (e.g., claude-1774210269126)
|
|
- Map CLI UUID → internal ID
|
|
- Write to DB
|
|
4. Session appears in Active Sessions immediately
|
|
```
|
|
|
|
**Shutdown flow:**
|
|
|
|
```
|
|
SIGTERM/SIGINT received
|
|
↓
|
|
1. adapter.destroy() → tmuxManager.killSession() → all tmux windows killed
|
|
2. dbSessions.clearAll() → clear sessions table
|
|
3. closeDB()
|
|
```
|
|
|
|
### DB Schema
|
|
|
|
```sql
|
|
CREATE TABLE sessions (
|
|
id TEXT PRIMARY KEY, -- internal ID (claude-1774210269126)
|
|
cli_session TEXT, -- CLI native UUID
|
|
adapter TEXT, -- 'claude' / 'codex' / 'gemini'
|
|
cwd TEXT,
|
|
window_id TEXT,
|
|
permission_mode TEXT,
|
|
created_at DATETIME DEFAULT (datetime('now')),
|
|
last_activity DATETIME DEFAULT (datetime('now'))
|
|
);
|
|
|
|
CREATE INDEX idx_sessions_cli ON sessions(cli_session);
|
|
CREATE INDEX idx_sessions_adapter ON sessions(adapter);
|
|
```
|
|
|
|
Migration: rename `claude_session` → `cli_session`, add `adapter` column (default `'claude'` for existing rows), remove `is_active` column.
|
|
|
|
### Chat Header Display
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────┐
|
|
│ ← code-tap 625c60d0-aedb-4e0b... [copy icon] │
|
|
│ claude-1774210269126 │
|
|
└──────────────────────────────────────────────────┘
|
|
```
|
|
|
|
- Primary: CLI UUID (truncated), click copy icon to copy full UUID → usable with `claude --resume <uuid>`
|
|
- Secondary: internal ID → usable with `tmux select-window -t codetap:claude-1774210269126`
|
|
|
|
`SESSION_CREATED` message updated to include both `sessionId` (internal) and `cliSessionId` (UUID).
|
|
|
|
### Hook Config Change
|
|
|
|
In `hook-config.ts`, SessionStart changes from file-writing script to `fireAndForget` API POST (same pattern as all other hooks):
|
|
|
|
```typescript
|
|
// Before:
|
|
SessionStart: [{ hooks: [{ type: 'command', command: hookPath, timeout: 2 }] }]
|
|
|
|
// After:
|
|
SessionStart: [{ hooks: [{ type: 'command', command: fireAndForget('session-start'), timeout: 2 }] }]
|
|
```
|
|
|
|
### SESSION_CREATED Message Payload
|
|
|
|
```typescript
|
|
// Before:
|
|
{ type: 'session-created', sessionId: string }
|
|
|
|
// After:
|
|
{ type: 'session-created', sessionId: string, cliSessionId: string }
|
|
```
|
|
|
|
`useChat` hook stores both IDs. `ChatView` header displays `cliSessionId` (primary) and `sessionId` (secondary).
|
|
|
|
### Recovery from Non-Graceful Shutdown
|
|
|
|
If the server crashes (kill -9, power loss) without running the shutdown flow:
|
|
|
|
1. Tmux session `codetap` may still be alive with running CLI instances
|
|
2. On next server start, DB still has session records (SQLite persists)
|
|
3. When hooks fire from surviving CLI instances → `resolveSessionId`:
|
|
- Finds the session in DB by `cli_session` UUID
|
|
- Restores the **original** internal ID from DB (e.g., `claude-1774210269126`)
|
|
- Re-creates in-memory mapping
|
|
- Session reappears in Active Sessions with its original ID
|
|
|
|
If the CLI session hasn't fired a SessionStart hook yet (e.g., Codex before first interaction):
|
|
- Session stays in DB with `cli_session = NULL`
|
|
- Once hook fires → DB record updated with CLI UUID
|
|
- UI shows UUID after hook fires (brief grace period showing internal ID only)
|
|
|
|
### CLI Changes (`bin/codetap`)
|
|
|
|
**`codetap new [--adapter <name>]`**
|
|
|
|
```bash
|
|
codetap new # WINDOW_NAME="claude-$(date +%s)", runs: claude
|
|
codetap new --adapter codex # WINDOW_NAME="codex-$(date +%s)", runs: codex
|
|
codetap new --adapter gemini # WINDOW_NAME="gemini-$(date +%s)", runs: gemini
|
|
```
|
|
|
|
Default adapter: `claude`. The `--adapter` flag determines both the window name prefix and the CLI command to run.
|
|
|
|
**`codetap --resume <id>`**
|
|
|
|
```
|
|
Input: internal ID or CLI UUID
|
|
↓
|
|
Is it internal ID format? ({adapter}-{digits})
|
|
├─ Yes → extract adapter from prefix, query DB for CLI UUID
|
|
│ ├─ Found → run: {adapter} --resume {uuid}
|
|
│ └─ Not found → error
|
|
└─ No (UUID format) → query DB by cli_session
|
|
├─ Found → get adapter from DB → run: {adapter} --resume {uuid}
|
|
└─ Not found → scan JSONL directories per adapter
|
|
├─ Found → detected adapter → run: {adapter} --resume {uuid}
|
|
└─ Not found → error: "Session not found"
|
|
```
|
|
|
|
**`codetap --continue [--adapter <name>]`**
|
|
|
|
Pass through to adapter CLI's native continue command:
|
|
- `claude --continue`
|
|
- `codex resume --last`
|
|
|
|
Window name: `{adapter}-{timestamp}` (same format as `new`).
|
|
|
|
SessionStart hook handles the mapping automatically when the CLI starts — even if the continued session was never managed by CodeTap before.
|
|
|
|
Default adapter: `claude`. With `--adapter codex`, runs codex's native continue command instead.
|
|
|
|
**`codetap -a / -A`**
|
|
|
|
Enhanced display:
|
|
|
|
```
|
|
Active sessions for code-tap:
|
|
|
|
1) claude-1774210269126
|
|
UUID: 625c60d0-aedb-4e0b-b78e-c9fbf0405e67
|
|
reply pong...
|
|
|
|
2) codex-1774210345678
|
|
UUID: abc12345-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
|
fix the login bug...
|
|
|
|
Select (1-2):
|
|
```
|
|
|
|
### Files to Modify
|
|
|
|
**Server:**
|
|
- `server/db.ts` — Schema migration, rename column, add `adapter` field, add `clearAll()`, remove session-map.json migration
|
|
- `server/adapters/claude/tmux-adapter.ts` — Remove `desktop-` logic from `resolveSessionId`, change `session-` to `claude-` in `startSession`, add `session-start` handler, restore original ID on recovery
|
|
- `server/adapters/claude/hook-config.ts` — Change SessionStart from `hookPath` script to `fireAndForget('session-start')`
|
|
- `server/adapters/claude/index.ts` — Add `session-start` hook route
|
|
- `server/adapters/codex/codex-tmux-adapter.ts` — Same pattern: `codex-` prefix, unified session-start handling
|
|
- `server/adapters/codex/index.ts` — Add `session-start` hook route if missing
|
|
- `server/adapters/interface.ts` — Add `adapter` field to `ActiveSessionInfo`
|
|
- `server/session-manager.ts` — Pass `cliSessionId` in `SESSION_CREATED` message
|
|
- `server/index.ts` — Call `dbSessions.clearAll()` in shutdown
|
|
- `server/config.ts` — Remove `sessionMap` path config
|
|
|
|
**Client:**
|
|
- `src/hooks/useChat.ts` — Store `cliSessionId` from `SESSION_CREATED`
|
|
- `src/components/ChatView.tsx` — Header shows CLI UUID (primary) + internal ID (secondary)
|
|
- `src/components/SessionsView.tsx` — No change (already shows `firstPrompt`)
|
|
|
|
**CLI:**
|
|
- `bin/codetap` — Add `--adapter` flag, change window naming, update resume/continue logic, enhance `-a`/`-A` display
|
|
- `bin/codetap-hook` — Delete (replaced by API POST)
|
|
|
|
### E2E Spec Updates (`tests/e2e-spec.feature`)
|
|
|
|
The following scenarios need to be updated to reflect the new session ID architecture:
|
|
|
|
1. **Chat header display** (L247): Update to show CLI UUID (primary) + internal ID (secondary) with copy icon
|
|
2. **CLI `--adapter` flag** (L1168-1475): Add scenarios for `codetap new --adapter`, `codetap --continue --adapter`
|
|
3. **Active sessions `-a`/`-A` display** (L1212): Update to show UUID + internal ID format
|
|
4. **session-map.json references** (L1308): Remove; update to DB-based recovery
|
|
5. **Session Deduplication regression** (L1829): Update to reflect Connect button fix (claudeSessionId → sessionId)
|
|
6. **SessionStart hook**: Add scenario documenting API POST flow (replaces file-writing script)
|
|
7. **tmux window naming** (L1176): Specify `{adapter}-{timestamp}` format
|
|
8. **Non-graceful restart recovery** (L1308): Add scenario for restoring original ID from DB
|
|
9. **Active session card UUID field** (L1548): Clarify where UUIDs appear (title vs expanded view)
|
|
|
|
### What Gets Removed
|
|
|
|
- `bin/codetap-hook` script
|
|
- `session-map.json` mechanism (writing, reading, migration)
|
|
- `desktop-` prefix logic in `resolveSessionId`
|
|
- `is_active` column from sessions table
|
|
- `sessionMap` path in config
|