https://github.com/jongwony/claudetasks.spoon
View and manage Claude Code tasks in a floating Hammerspoon window with live updates.
https://github.com/jongwony/claudetasks.spoon
claude-code hammerspoon task
Last synced: 12 days ago
JSON representation
View and manage Claude Code tasks in a floating Hammerspoon window with live updates.
- Host: GitHub
- URL: https://github.com/jongwony/claudetasks.spoon
- Owner: jongwony
- License: mit
- Created: 2026-01-27T15:58:37.000Z (20 days ago)
- Default Branch: main
- Last Pushed: 2026-01-31T14:09:30.000Z (16 days ago)
- Last Synced: 2026-01-31T14:22:57.834Z (16 days ago)
- Topics: claude-code, hammerspoon, task
- Language: Lua
- Homepage:
- Size: 87.9 KB
- Stars: 22
- Watchers: 0
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ClaudeTasks.spoon
Hammerspoon Spoon for viewing Claude Code tasks in a floating window.
## Demo
## Features
- Floating task viewer with WebView UI
- **Vim-like keyboard navigation** (j/k to move, Space to view, Enter to launch)
- **Task search/filtering** with real-time results
- Auto-refresh on file changes via pathwatcher
- Session selector with datalist autocomplete
- Quick TaskUpdate via dialog (⌘E)
- Launch Claude session in terminal (▶ button)
- Task detail view with metadata display
- Keyboard shortcuts help popup (?)
## Installation
### Option 1: Clone and Symlink (Recommended for development)
```bash
git clone https://github.com/jongwony/ClaudeTasks.spoon.git
ln -sf $(pwd)/ClaudeTasks.spoon ~/.hammerspoon/Spoons/ClaudeTasks.spoon
```
### Option 2: Direct Download
Download and extract to `~/.hammerspoon/Spoons/ClaudeTasks.spoon/`
## Usage
Add to your `~/.hammerspoon/init.lua`:
```lua
hs.loadSpoon("ClaudeTasks")
spoon.ClaudeTasks:bindHotkeys(spoon.ClaudeTasks.defaultHotkeys)
spoon.ClaudeTasks:start()
```
### Default Hotkeys
| Hotkey | Action |
|--------|--------|
| `opt+.` | Toggle task viewer |
| `cmd+alt+T` | Show task status summary |
### In-App Keyboard Shortcuts
| Key | Action |
|-----|--------|
| `j` / `k` | Navigate tasks (vim-like) |
| `Space` | View task detail |
| `Enter` | Launch Claude session |
| `/` | Search mode |
| `=` | Session input mode |
| `Escape` | Return to navigation |
| `?` | Show shortcuts help |
| `⌘E` | Quick Task dialog |
| `⌘Enter` | Create task |
### Custom Configuration
```lua
hs.loadSpoon("ClaudeTasks")
spoon.ClaudeTasks:configure({
width = 500,
height = 700,
margin = 30,
debugMode = true,
-- Specify paths explicitly if auto-discovery fails
claudePath = "/usr/local/bin/claude",
terminalApp = "/Applications/iTerm.app/Contents/MacOS/iTerm2",
shell = "/bin/bash",
})
spoon.ClaudeTasks:bindHotkeys({
toggle = {{"cmd", "alt"}, "T"},
status = {{"cmd", "alt", "shift"}, "T"}
})
spoon.ClaudeTasks:start()
```
## API
### Methods
- `obj:init()` - Initialize the Spoon (called automatically)
- `obj:start()` - Start file watching and load saved state
- `obj:stop()` - Stop file watching and cleanup
- `obj:show()` - Show the task viewer
- `obj:hide()` - Hide the task viewer
- `obj:toggle()` - Toggle visibility
- `obj:refresh()` - Manually refresh the task list
- `obj:setTaskListId(id)` - Set the session ID filter
- `obj:createTask(subject)` - Create a new task via Claude CLI
- `obj:quickTaskUpdate(prompt)` - Run quick TaskUpdate via haiku model
- `obj:launchClaudeWithTaskList()` - Launch Claude in terminal with current session
- `obj:launchClaudeWithCwd(sessionId, cwd)` - Launch Claude with specific working directory
- `obj:launchClaudeWithSession(sessionId)` - Launch Claude with session env var
- `obj:showTaskDetailWindow(subject, description, metadata)` - Show task detail popup
- `obj:status()` - Get current status info
- `obj:configure(options)` - Update configuration
- `obj:bindHotkeys(mapping)` - Bind hotkeys
### Configuration Options
| Option | Default | Description |
|--------|---------|-------------|
| `width` | 420 | Window width |
| `height` | 580 | Window height |
| `margin` | 20 | Screen edge margin |
| `refreshDebounce` | 0.2 | Debounce delay for file changes (seconds) |
| `debugMode` | false | Enable debug logging |
| `taskListId` | `$CLAUDE_CODE_TASK_LIST_ID` | Session ID filter |
| `claudePath` | nil | Path to claude CLI (auto-discovered if nil) |
| `terminalApp` | nil | Path to terminal app (auto-discovered if nil) |
| `shell` | nil | Shell to use (defaults to `$SHELL` or `/bin/zsh`) |
## Requirements
- Hammerspoon
- Claude Code CLI (`claude` command)
- A supported terminal app (Ghostty, iTerm2, or Terminal.app)
## License
MIT License - see [LICENSE](LICENSE)