npm package: @mondaydotcomorg/monday-dev-tui
Description: A keyboard-driven terminal UI for managing Monday.com sprint boards
Author: Yoav Tenne
Latest version: 0.5.0

# monday-dev-tui

A fast, keyboard-driven terminal UI for managing your Monday.com sprint board — built with [Ink](https://github.com/vadimdemedes/ink) (React for CLIs).

## Features

- **Two-panel TUI** — task list on the left, full task detail on the right
- **Instant filter switching** — toggle between _My Tasks_ and _Full Sprint_ with a single key
- **Inline status changes** — change task status without leaving the terminal
- **Update management** — add updates via `$EDITOR`, view them inline or in a pager
- **Claude AI integration** — open a Claude session per task in a tmux window or iTerm2 tab
- **Git worktrees** — create a worktree for the current task with one keypress
- **VS Code integration** — jump to the task's repo in VS Code
- **Optimistic UI** — status changes reflect instantly; revert automatically on API error

```
┌─[1] My Tasks  [2] Active Sprint ───────────────────────────────── 7/42 tasks ─┐
│                                                                                 │
│ ┌── Tasks ────────────────────────┐  ┌── COLL-429 — Detail ──────────────────┐ │
│ │ ● COLL-429  Fix auth token exp… │  │  COLL-429  ● Claude                   │ │
│ │   COLL-431  Add retry logic     │  │  Refresh auth tokens on expiry         │ │
│ │   COLL-434  Update docs         │  │                                        │ │
│ │   COLL-438  Perf regression     │  │  Status:       In Progress             │ │
│ └─────────────────────────────────┘  │  Priority:     High                    │ │
│                                      │  Type:         Bug                     │ │
│                                      │  Owners:       Alice                   │ │
│                                      │  Sprint:       Q1 Sprint 3             │ │
│                                      │  Story Points: 3 est / 2 actual        │ │
│                                      │  Repository:   backend                 │ │
│                                      │  Worktree:     ~/worktrees/COLL-429    │ │
│                                      └────────────────────────────────────────┘ │
│  Tab=panel  s=status  w=repo  t=worktree  c=claude  v=iterm2  p=path  q=quit   │
└─────────────────────────────────────────────────────────────────────────────────┘
```

## Screenshots

![Task detail view](docs/screenshots/task-detail.png)

![Status dropdown](docs/screenshots/status-dropdown.png)

![Settings screen](docs/screenshots/settings.png)

## Requirements

| Requirement | Notes |
|---|---|
| Node.js ≥ 22.19.0 | |
| Monday.com account | Personal API token required |
| tmux | Optional — required for `c` (Claude sessions) |
| macOS | `v` (iTerm2) and clipboard features are macOS-only; core TUI works on Linux |

## Installation

### From npm (recommended)

```bash
npm install -g @mondaydotcomorg/monday-dev-tui
```

### From source

```bash
git clone https://github.com/DaPulse/monday-dev-tui.git
cd monday-dev-tui
npm install
npm run build
npm link
```

## Quick Start

**1. Get your Monday.com API key**

Go to monday.com → _Profile_ → _Developers_ → _My Access Tokens_ → generate a personal token.

**2. Export the API key**

```bash
export MONDAY_API_KEY=your_token_here
# Add to ~/.zshrc or ~/.bashrc to persist it
```

**3. Launch and configure**

```bash
monday-dev-tui
```

On first launch, a settings screen lets you enter:
- **Board ID** — the numeric ID in your board's URL (`monday.com/boards/12345678`)
- **Subdomain** — your workspace subdomain (`acme` for `acme.monday.com`)

**4. Press `?` or check the status bar** for all available keybindings.

## Monday.com Board Setup

monday-tui expects the following **column IDs** on your board. You can rename the display labels but the IDs must match:

### Mandatory Columns

These columns **must** exist for the TUI to function:

| Column ID | Type | Purpose |
|---|---|---|
| `task_status` | Status | Task status — required for status change mutations |
| `mirror` | Mirror | Active sprint indicator (mirrors the related sprint's "active" field) — required for sprint filtering |
| `item_id` | Item ID | Formatted task ID (`COLL-453`) — required for task identification |

### Optional Columns

These columns enhance functionality but the TUI will work without them:

| Column ID | Type | Purpose |
|---|---|---|
| `task_priority` | Status | Priority level |
| `task_type` | Status | Task type (Bug, Feature, etc.) |
| `task_owner` | People | Assignees (required for "My Tasks" filter) |
| `task_sprint` | Board Relation | Sprint reference |
| `task_estimation` | Numbers | Estimated story points |
| `task_actual_effort` | Numbers | Actual story points |
| `check` | Checkbox | Marks a task as unplanned |

> **Note**: These column IDs are configured in your Monday.com board settings. If your board uses different IDs, you'll need to update the GraphQL queries in `src/api/monday.ts`.

## Keybindings

### Global

| Key | Action |
|---|---|
| `q` | Quit |
| `g` | Open settings |
| `r` | Refresh board |
| `1` | Filter: My Tasks (current sprint) |
| `2` | Filter: Full active sprint |
| `Tab` | Switch panel focus (list ↔ detail) |

### Task List

| Key | Action |
|---|---|
| `j` / `↓` | Move down |
| `k` / `↑` | Move up |
| `Enter` | Focus detail panel |

### Task Detail

| Key | Action |
|---|---|
| `s` | Change status (dropdown) |
| `w` | Assign repository |
| `t` | Create / open git worktree |
| `u` | Add update (opens `$EDITOR`) |
| `o` | View all updates in pager |
| `c` | Open Claude in a tmux window |
| `v` | Open Claude in an iTerm2 tab (macOS) |
| `x` | Close Claude session |
| `l` | Copy Monday.com item link to clipboard |
| `p` | Set path override for this task |
| `e` | Open VS Code at task's repo/worktree path |

## Configuration

Config is stored at `~/.monday-tui.json` (override with `MONDAY_TUI_CONFIG` env var):

```json
{
  "boardId": "12345678",
  "subdomain": "acme",
  "repoMap": {
    "backend": "/Users/you/projects/backend",
    "frontend": "/Users/you/projects/frontend"
  },
  "taskRepos": {
    "item_internal_id_123": "backend"
  },
  "pathOverrides": {
    "COLL-453": "/Users/you/projects/custom-branch"
  },
  "worktrees": {
    "COLL-429": "/Users/you/worktrees/COLL-429"
  },
  "worktreeBaseDir": "/Users/you/worktrees"
}
```

| Field | Description |
|---|---|
| `boardId` | Monday.com board numeric ID |
| `subdomain` | Monday.com workspace subdomain |
| `repoMap` | Map of label → local repo path (configured in Settings via `g`) |
| `taskRepos` | Map of task's internal Monday ID → repo label (set via `w`) |
| `pathOverrides` | Manual path overrides per task ID (set via `p`) |
| `worktrees` | Paths created by the worktree feature (set via `t`) |
| `worktreeBaseDir` | Base directory for new worktrees. If unset, worktrees are placed alongside the repo. |

**Path resolution priority** (for Claude sessions, VS Code, worktrees):
`worktrees[taskId]` → `pathOverrides[taskId]` → `repoMap[taskRepos[id]]`

## Claude AI Integration

Press `c` to open a Claude coding session for the selected task:

- Creates a named tmux window/session (`monday-COLL-NNN`)
- Runs `claude --dangerously-skip-permissions` in the task's repo directory
- Press `v` to attach in a new iTerm2 tab (macOS only)
- Press `x` to close the session
- Active sessions are indicated by a green `● Claude` badge in the detail panel

If not inside tmux, you'll receive a `tmux attach` command to run in a new terminal.

## Git Worktrees

Press `t` to create a git worktree for the selected task:

1. If the task has a repo assigned (`w`), uses that repo as the base
2. If no repo is assigned, shows a repo picker
3. Creates a new git branch named after the task ID (e.g., `COLL-429`)
4. Worktree path: `<worktreeBaseDir>/<COLL-429>` if configured, otherwise a sibling of the base repo
5. Automatically sets the task's path override to the worktree path

If the branch already exists, the existing branch is checked out in the new worktree.

The worktree path is shown in the task detail as **Worktree** (green). If the path is deleted externally (`git worktree remove` or manually), it turns **red** with a warning — clear it with `p` or recreate with `t`.

## Platform Notes

| Feature | macOS | Linux |
|---|---|---|
| Core TUI | ✅ | ✅ |
| tmux integration | ✅ | ✅ |
| Claude sessions | ✅ | ✅ |
| Clipboard (`l`) | ✅ pbcopy | ❌ |
| iTerm2 (`v`) | ✅ | ❌ |
| VS Code (`e`) | ✅ | ✅ |
| Git worktrees (`t`) | ✅ | ✅ |

## Development

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

[MIT](./LICENSE)