monday-tui

A fast, keyboard-driven terminal UI for managing your Monday.com sprint board — built with 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

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)

npm install -g monday-tui

From source

git clone https://github.com/yoavte/monday-tui.git
cd monday-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

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

3. Launch and configure

monday-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:

| Column ID | Type | Purpose | |---|---|---| | item_id | Item ID | Formatted task ID (COLL-453) | | task_status | Status | Task status | | task_priority | Status | Priority level | | task_type | Status | Task type (Bug, Feature, etc.) | | task_owner | People | Assignees | | task_sprint | Board Relation | Sprint reference | | mirror | Mirror | Active sprint indicator (mirrors the related sprint's "active" field) | | 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):

{
  "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.

License

MIT