Concepts
aven stores tasks in a local SQLite database. The TUI is the human interface, and the CLI is the automation and agent interface.
Every command runs inside one active workspace. Inside that workspace, projects usually map to repositories or directories, and tasks carry status, priority, labels, descriptions, notes, refs, and relationships.
The queue is aven’s default attention view for open tasks.
Workspaces, projects, tasks, and labels
Section titled “Workspaces, projects, tasks, and labels”A workspace is a task universe. Use workspaces to isolate personal tasks, work tasks, or any other separate context. Tasks in different workspaces stay separate.
A project groups tasks inside a workspace. Projects commonly map to repositories or directories. By default, aven infers the project from the current repository or directory name.
A task is a unit of work inside a workspace and, usually, a project. It has a title, workflow state, content, identity, and relationships.
Labels are cross-cutting tags such as bug, docs, or ux. Label names are normalized before storage: uppercase letters become lowercase, and punctuation or spaces become dashes. Create a label explicitly, then assign it to tasks.
Status and priority
Section titled “Status and priority”Statuses describe lifecycle:
| Status | Meaning |
|---|---|
inbox |
Captured work that needs triage |
backlog |
Work for later |
todo |
Ready work |
active |
Work in progress |
done |
Completed work |
canceled |
Intentionally dropped work |
Open tasks have inbox, backlog, todo, or active status. Terminal tasks have done or canceled status.
Priorities affect queue placement and sorting: none, low, medium, high, and urgent.
Descriptions and notes
Section titled “Descriptions and notes”Use descriptions for the main body of a task: problem statement, acceptance criteria, relevant links, and implementation details.
Notes are append-style entries attached to a task. Use notes for decisions, blockers, partial progress, and follow-up details. Notes appear in full task reads and can be deleted when needed.
aven prints display refs such as APP-7KQ9 so tasks are easy to mention in commands, notes, and handoffs.
A qualified ref has two parts:
APP: the project prefix. This gives display context.7KQ9: the task id suffix. aven lengthens the suffix when needed so refs stay unique inside a workspace.
Prefer the qualified ref printed by command output. Bare suffix refs such as 7KQ9 work when they are unambiguous. When you type a suffix ref in a command, it must contain at least three characters.
Dependencies and epics
Section titled “Dependencies and epics”Dependencies model ordering. If task A depends on task B, task B must finish before task A can start. Tasks with unresolved open dependencies are blocked.
Dependencies cannot point to the same task, cross workspaces, or form cycles.
Epics group related work. An epic is a task that contains child tasks. Use epics when several tasks belong to one larger effort.
Epic children belong to the same workspace and project as the epic. Each child belongs to one epic. An epic child is a regular task, and blocking behavior comes from dependencies.
Use epics for grouping. Use dependencies for ordering.
The queue is the default attention view in the TUI. It answers: what should I look at next?
Tasks are grouped from most urgent to least urgent:
- Needs action: sync conflicts, urgent tasks, and stale active tasks
- Blocked: tasks with unresolved open dependencies
- Focus: active tasks and high-priority todo tasks
- Triage: inbox tasks and medium-priority todo tasks
- Later: backlog tasks, low-priority todo tasks, and todo tasks with no priority
A stale active task is active work that has gone without updates long enough to need attention.
Inside a group, queue order is stable and favors important statuses, higher priorities, stale active work, and older tasks.
Deleted tasks
Section titled “Deleted tasks”Deleted tasks are soft-deleted. They are hidden from normal task views and stay available through explicit deleted-task list and search options.
Sync conflicts
Section titled “Sync conflicts”When sync is enabled, the same task can be edited in more than one place before changes sync. aven records conflicts by field instead of overwriting either side.
Conflicted tasks appear in the TUI and can be inspected before you choose the final value.
Context resolution
Section titled “Context resolution”aven resolves the active workspace from --workspace, the longest matching workspace route, workspace.default, the built-in default, or the only existing workspace.
Workspace routes match the current directory before project inference. Configure routes when paths such as ~/work or ~/personal should select different task universes.
Project path mappings override project inference when a path should belong to a specific project. Use them when a checkout directory has a short name, a generated name, or a name that differs from the project you want in task refs.
Use aven doctor to inspect the active config, database path, workspace, and project for the current directory. See Configuration for the full config shape.