🚀 Getting Started
Installation
LazyArchon can be installed using several methods. Choose the one that works best for your setup:
📜
One-Line Script (Recommended)
Download and install LazyArchon with a single command
🍺
Homebrew (macOS/Linux)
Install via Homebrew package manager
Go
Go Install
Install directly from Go source code
📦
Binary Downloads
Download pre-built binaries from GitHub Releases
🤖 Claude & MCP
LazyArchon ships with a built-in MCP server: lazyarchon mcp. It exposes the same tasks and projects as the TUI through the same backend, so you and your AI client work on one database:
Claude ── stdio (JSON-RPC) ── lazyarchon mcp ── backend (local by default)Setup
One command registers the server for your user:
Terminal
claude mcp add lazyarchon -- lazyarchon mcpTo pin a specific binary path instead:
Terminal
claude mcp add lazyarchon -- /usr/local/bin/lazyarchon mcp Or make it project-scoped — commit a .mcp.json so every session in the repo gets the server:
.mcp.json
{
"mcpServers": {
"lazyarchon": {
"command": "lazyarchon",
"args": ["mcp"]
}
}
}Try it
Then just ask:
- › "list my projects"
- › "add a high-priority task to review the PR, due Friday"
- › "mark it done"
Changes the client makes appear in the TUI after a refresh (r), and your TUI edits are visible to the client — one SQLite database, two faces.
Tool reference
Ten typed tools. List tools return compact summaries; get/create/update tools return the full object. All timestamps are RFC3339 UTC.
Projects
| Tool | Arguments | Notes |
|---|---|---|
| list_projects | — | Compact summaries plus total |
| get_project | project_id | Full project incl. description, color, extra |
| create_project | title, description?, color?, pinned? | Local backend only |
| update_project | project_id, title?, description?, color?, pinned? | Only changed fields |
| delete_project | project_id, delete_tasks? | Refuses while tasks exist unless delete_tasks: true |
Tasks
| Tool | Arguments | Notes |
|---|---|---|
| list_tasks | project_id?, status?, search?, tags?, include_archived?, limit?, offset? | Summaries plus total, has_more, next_offset |
| get_task | task_id | Full task incl. description and extra fields |
| create_task | title, project_id?, parent_id?, description?, status?, priority?, assignee?, tags?, due_date?, sources?, code_examples? | project_id optional when exactly one project exists |
| update_task | task_id + any settable field | Omitted fields are unchanged |
| delete_task | task_id | Subtasks survive with parent_id cleared |
? marks optional arguments. Project writes are supported by the local backend; HTTP backends (archon, gitea, vikunja) return a clear "not supported" error instead.
Semantics worth knowing
- ›Statuses:
todo,doing,review,done— validated, anything else is an error. - ›Priority: 1 = critical, 2 = high, 3 = medium (default), 4 = low. Lower is more urgent.
- ›Due dates:
YYYY-MM-DDor RFC3339. Onupdate_task, an empty string clears the value (same forparent_id). - ›Nesting: pass
parent_idto create a subtask. Deleting a parent leaves the children in place, parentless. - ›Archiving:
update_taskwitharchived: truehides the task from lists unlessinclude_archived: true. - ›Pagination:
list_tasksdefaults to 500 per page; follownext_offsetwhilehas_moreis true. - ›Logs: the server logs to a file (default
/tmp/lazyarchon.log), never stdout — stdout is the protocol.
📖 User Guide
Interface Overview
LazyArchon features a clean two-panel layout inspired by terminal file managers like ranger and lf:
Left Panel - Task List
- • Browse all tasks in the current project
- • Visual status indicators for each task
- • Quick navigation with vim-like keys
- • Filter by features and projects
Right Panel - Task Details
- • Full task description with markdown
- • Task metadata (status, assignee, features)
- • Scrollable content for long descriptions
- • Rich text formatting and syntax highlighting
Task Status Indicators
Status Symbols
○
Todo
Task not started yet
◐
Doing
Task in progress
◉
Review
Task under review
●
Done
Task completed
Visual Indicators
▓░
Scroll Bar
Position indicator with progress
[Tasks]
Active Panel
Bright border indicates focus
[Details]
Inactive Panel
Dimmed when not focused
⌨️ Keyboard Shortcuts
Complete reference for all keyboard shortcuts in LazyArchon. Press ? in-app for help.
Panel Navigation & Movement
h
Switch to left panel (Tasks)
l
Switch to right panel (Details)
j/kor↑/↓
Navigate/scroll in active panel (1 line)
J/K
Fast scroll in active panel (4 lines)
Ctrl+u/d
Half-page scroll in active panel
gg
Jump to first item in active panel
G
Jump to last item in active panel
| Key | Action |
|---|---|
| h | Switch to left panel (Tasks) |
| l | Switch to right panel (Details) |
| j/kor↑/↓ | Navigate/scroll in active panel (1 line) |
| J/K | Fast scroll in active panel (4 lines) |
| Ctrl+u/d | Half-page scroll in active panel |
| gg | Jump to first item in active panel |
| G | Jump to last item in active panel |
Task Management
t
Change task status (Todo/Doing/Review/Done)
e
Edit task features (assign/create features)
f
Filter by features (multi-select modal)
s
Change sorting criteria (cycle through modes)
| Key | Action |
|---|---|
| t | Change task status (Todo/Doing/Review/Done) |
| e | Edit task features (assign/create features) |
| f | Filter by features (multi-select modal) |
| s | Change sorting criteria (cycle through modes) |
Project Management
p
Enter project selection mode
a
Show all tasks (exit project filter)
Enter
Select project in project mode
Escape
Cancel project selection
| Key | Action |
|---|---|
| p | Enter project selection mode |
| a | Show all tasks (exit project filter) |
| Enter | Select project in project mode |
| Escape | Cancel project selection |
Application Controls
r
Refresh data from API
?
Show help modal
q
Quit application
Escape
Close modals/cancel operations
| Key | Action |
|---|---|
| r | Refresh data from API |
| ? | Show help modal |
| q | Quit application |
| Escape | Close modals/cancel operations |
🔧 Troubleshooting
Common Issues
Tasks not loading (local mode)
Error: Failed to load tasks: unable to open database file• Check the database path configured via
LAZYARCHON_DB_PATH or plugins.local.path• Make sure the directory exists and is writable
• Check the log at
/tmp/lazyarchon.log for details• If another process holds a stale lock, close other LazyArchon instances and retry
Connection refused (Gitea / Vikunja / Archon backends)
Error: Failed to load tasks: dial tcp [::1]:8181: connect: connection refused• Ensure the backend server is running and reachable at the URL in your config
• Check if the server is accessible:
curl http://localhost:8181/health• Verify firewall settings aren't blocking the connection
• Confirm
plugin: in config.yaml points at the backend you intend to useCommand not found after installation
lazyarchon: command not found• Check if installation directory is in PATH
• For Go install: Add
$(go env GOPATH)/bin to PATH• For script install: Add
~/.local/bin to PATH• Restart your terminal after modifying PATH
Terminal display issues
• Ensure terminal supports ANSI colors (most modern terminals do)
• Try running in a different terminal emulator
• Check terminal size: LazyArchon requires minimum 80x24
• Verify UTF-8 support is enabled
Performance issues
• Large task lists may cause slower rendering
• Use project filtering (p key) to reduce displayed items
• Refresh data (r key) if UI becomes unresponsive
• Consider filtering by features to reduce dataset size
Getting Debug Information
Manual API Testing
Test your API connection manually:
$
$