Configuration

aven works without a config file. Add one when defaults are not enough.

aven config init

aven reads config.yaml from AVEN_CONFIG_DIR when set, otherwise from ~/.config/aven.

Scalar values from scripts and agents

aven config get reads these non-secret scalar settings:

Key	Values
sync.enabled	true or false
sync.server_url	JSON-quoted HTTP URL, or null when unset
sync.interval_seconds	Positive integer, with the default resolved to 30
update.automatic_checks	true or false
local.db_path	JSON-quoted path, or null when unset
local.image_optimization	off, paste, or on

aven config get sync.server_url
aven config set sync.enabled true
aven config set sync.server_url https://sync.example.com
aven config set local.db_path null

aven config set <key> <value> validates the value, updates only that scalar in config.yaml, and preserves comments and unrelated settings. The write replaces the file atomically. Use null to clear sync.server_url or local.db_path. Configuration keys containing secrets, including sync.auth_token, are not available through config get or config set.

Use aven doctor to inspect the active config, database path, workspace, project, sync cursor, daemon wake address, and routing decisions. Doctor still produces a redacted report when this file is malformed, unreadable, or contains an invalid value. It includes available YAML line and column context without printing config values that may contain secrets.

When configuration prevents startup, run aven doctor --db /expected/path/to/db.sqlite to bypass database path resolution while retaining the config finding. Doctor does not rewrite the config, create the selected database, or run database migrations. After correcting the file, rerun doctor before starting an ordinary command. Use aven doctor --json --fail-on-error in recovery automation.

Config shape

local:
  db_path: "/path/to/aven.sqlite"
  blob_dir: "/path/to/aven-blobs"
  inline_images: auto
  image_optimization: off
  attachment_lifecycle:
    grace_days: 7
    server_grace_days: 30
    quota_bytes: 10737418240
    server_workspace_quota_bytes: 10737418240
    preview_quota_bytes: 536870912
    maintenance_limit: 128

workspace:
  default: "personal"
  routes:
    - workspace: "work"
      paths: ["~/work"]

project:
  overrides:
    - project: "aven"
      paths: ["~/code/aven"]

sync:
  enabled: true
  server_url: "http://127.0.0.1:3000"
  auth_token: "shared-secret"
  interval_seconds: 30

daemon:
  wake_addr: "127.0.0.1:47631"

update:
  automatic_checks: true

tui:
  table:
    columns: [ref, title, labels, metadata, project, status, priority, time]
  sidebar:
    views:
      - queue
      - ready
      - blocked
      - overdue
      - all
      - open
      - inbox
      - active
      - backlog
      - todo
      - upcoming
      - done
      - conflicts
      - epics
      - recurring
      - recent_actions
      - search
  columns:
    - name: "Inbox"
      statuses: [inbox]
    - name: "Backlog"
      statuses: [backlog]
    - name: "Todo"
      statuses: [todo]
    - name: "Active"
      statuses: [active]
    - name: "Done"
      statuses: [done, canceled]
  commands:
    - name: dispatch
      aliases: [custom-dispatch]
      description: "Open the selected task in its tmux workspace"
      program: "~/bin/dispatch-task"
      keys: [z d]
      detail_keys: [z D]
      requires: selected-task
      execution: wait
      on_success: quit

agent:
  task_intake:
    command: "claude"
    args: ["-p", "--no-session-persistence", "--bare", "{prompt}"]
    timeout_seconds: 45

Database path

Tasks live in SQLite. aven resolves the database path from --db, then AVEN_DB, then local.db_path, then the default state directory.

Use local.db_path when you want an explicit database location:

local:
  db_path: "~/tasks/aven.sqlite"

Attachment lifecycle

All image attachment settings are optional. The defaults support normal use without configuration.

Storage location

local.blob_dir selects the directory that stores attachment image files. Absolute paths are used as written. Relative paths are resolved beside the active database. When omitted, Aven creates a sidecar directory beside the database. Use aven backup when copying Aven data because copying only the SQLite database does not include these image files.

Image previews

local.inline_images controls whether the TUI draws image previews or shows text labels. Locally available images remain focusable and can open in the operating system viewer in every mode:

Value	Behavior
off	Always show text labels without inline previews.
auto	Show previews in supported terminals outside tmux and labels everywhere else. This is the default.
on	Show previews in supported terminals and enable tmux passthrough.

Aven uses the iTerm2 inline-image protocol in iTerm2 and the Kitty graphics protocol in Kitty, WezTerm, Ghostty, and Warp. Setting on helps these protocols pass through tmux, but cannot add image support to another terminal. Sixel-only terminals show text labels.

Detection uses terminal markers such as TERM_PROGRAM, TERM, KITTY_WINDOW_ID, WEZTERM_PANE, GHOSTTY_RESOURCES_DIR, and WARP_TERMINAL_SESSION_UUID. See Image attachments for controls and Troubleshoot image previews for setup help.

PNG optimization

local.image_optimization controls lossless PNG optimization:

Value	Behavior
off	Preserve images unless attachment add --optimize overrides it. This is the default.
paste	Optimize pasted images and preserve CLI file attachments.
on	Optimize pasted images and CLI file attachments unless --no-optimize overrides it.

Optimization applies only to PNG files. Aven preserves the original when optimization fails or does not reduce the file size, and validates any optimized file before storage. Cached previews are disposable, regenerate when needed, and are excluded from sync, backup, export, and import.

Retention and storage limits

Setting	Default	Purpose
grace_days	7 days	Minimum age before an unused local image becomes eligible for cleanup.
server_grace_days	30 days	Minimum age before an unused server image becomes eligible for cleanup.
quota_bytes	10 GiB	Maximum unique attachment image storage on one device.
server_workspace_quota_bytes	10 GiB	Maximum unique attachment image storage for one server workspace.
preview_quota_bytes	512 MiB	Maximum disposable preview-cache size.
maintenance_limit	128	Maximum files processed in one cleanup run.

Images used by tasks or attachment operations in progress are protected from cleanup. Identical images share storage and count once toward attachment quotas. The preview cache uses its separate quota and does not count toward image-file quotas. aven attachment prune performs a dry run unless you pass --apply.

Workspace routes

A workspace is a task universe. Workspace routes choose the active workspace from the current directory.

workspace:
  default: "personal"
  routes:
    - workspace: "work"
      paths: ["~/work"]

A --workspace flag overrides route inference for one command.

Project path mappings

Projects commonly map to repositories or directories. By default, aven infers the project from the current repository or directory name.

Project overrides make that inference explicit when a path should belong to a specific project:

project:
  overrides:
    - project: "aven"
      paths: ["~/code/aven"]

Sync and daemon settings

Sync is optional and self-hosted. Configure sync when aven sync and aven daemon should use a default server:

sync:
  enabled: true
  server_url: "http://127.0.0.1:3000"
  auth_token: "shared-secret"
  interval_seconds: 30

daemon:
  wake_addr: "127.0.0.1:47631"

Loopback wake address

Daemon wake addresses must be loopback.

Automatic update checks

The TUI checks for releases in the background and shows an update badge when a release is available. Set automatic_checks to false to disable these automatic checks and notifications:

update:
  automatic_checks: false

Set AVEN_NO_UPDATE_CHECK=1 to disable automatic checks for one environment. The environment variable takes precedence over update.automatic_checks. aven update and the TUI’s explicit update command are available with either setting.

TUI robot column

This experimental column makes it easier to spot tasks created by agents, using CLI creation as the indicator. It is opt-in and disabled by default.

Add robot before title in tui.table.columns to show a dim Nerd Font robot for CLI-created tasks.

tui:
  table:
    columns: [ref, robot, title, labels, metadata, project, status, priority, time]

TUI-created, API-created, iOS-created, and unknown historical sources stay blank.

TUI sidebar views

tui.sidebar.views controls which task views appear in the sidebar and their order. Edit the local config file and restart the TUI to apply changes. The available names are queue, ready, blocked, overdue, all, open, inbox, active, backlog, todo, upcoming, done, conflicts, epics, recurring, recent_actions, and search.

For example, this keeps a compact set of views:

tui:
  sidebar:
    views: [queue, ready, upcoming, done]

An empty list (views: []) hides every task view from the sidebar while keeping the section headings and project scope navigation. Hidden views remain available through the command palette, header view menu, and keyboard shortcuts. Selecting a hidden view keeps it hidden in the sidebar. Aven rejects unknown or duplicate names. Remove sidebar or views to restore the default 17-view order shown in the full config example.

TUI table columns

tui.table.columns sets which task-list columns appear and their order. Edit the local config file and restart the TUI to apply changes. The default order is:

tui:
  table:
    columns: [ref, title, labels, metadata, project, status, priority, time]

List the columns in the order you want them to appear. Remove a name to hide that column. Aven rejects empty lists, unknown names, and duplicates. Omit columns to use the default columns and order.

Name	Content
ref	Task reference, selection and mark indicators, and epic tree markers
title	Task title, including inline title editing
robot	Optional agent creation marker, hidden by default
labels	Label summary, or child rollup summary in the Epics view
metadata	The blank-headed indicator column: notes, dependencies, epic relationships, overdue, deleted and deferred markers
project	Project key
status	Status icon and text, or icon only with compact status
priority	Priority indicator, headed P
time	Time value with a context-dependent heading: IDLE, WHEN, DUE, ACT, TIME, or AGE

The title expands into remaining space when shown. Columns size automatically and may collapse when empty, even when listed in the configuration. Narrow tables hide labels; in Epics, the summary stays visible and project is hidden instead.

Selection and mark indicators appear in ref, or in title if ref is hidden or too narrow. If neither column has room, the indicators appear in a separate three-character area at the left of the table. Editing a hidden title opens a text editor dialog. You can still edit a hidden status with the keyboard, but there is no status cell to click.

This setting does not change board lanes (tui.columns), group ordering, the selected-task preview, or the separate Recurring and Recent Actions tables.

Compact status column

tui.table.compact_status renders the task list status column as one icon per task instead of icon and text, and shortens the column header to S. This keeps narrow task lists readable without hiding status. Every status has its own icon:

Status	Icon
inbox	▣
backlog	◌
todo	□
active	●
done	✓
canceled	×

tui:
  table:
    compact_status: true

The option is off by default. It applies to the task list status column, including epics and their expanded child rows, and to the status marker on column-board cards. Task details, status pickers, and the selected-task preview continue to show status text. Hiding status from tui.table.columns still hides the column entirely.

TUI columns

The columns layout groups Aven’s semantic statuses into named lanes. Names and order are presentation settings. Task status values remain inbox, backlog, todo, active, done, and canceled across the CLI, sync, queue, dependencies, and agent workflows.

The default board keeps every status visible:

tui:
  columns:
    - name: "Inbox"
      statuses: [inbox]
    - name: "Backlog"
      statuses: [backlog]
    - name: "Todo"
      statuses: [todo]
    - name: "Active"
      statuses: [active]
    - name: "Done"
      statuses: [done, canceled]

Lanes use workflow-specific ordering. Inbox shows the oldest tasks first, Backlog and Todo sort by priority and then age, Active shows the stalest activity first, and Done shows the most recently completed or canceled tasks first. Custom lanes that combine statuses from different workflow stages preserve the active task-list order.

Customize lane names, order, and grouping by editing this list. Each fixed status must appear exactly once. Aven rejects empty columns, unknown statuses, duplicates, and incomplete mappings so the board cannot hide tasks accidentally.

The first status in each lane is its movement destination. For example, moving a task into the default Done lane sets its status to done. Choosing the lane a task already occupies preserves its existing status, including canceled within Done.

Custom TUI commands

tui.commands adds trusted local programs to the TUI command palette. Commands receive versioned task and workspace context as JSON through standard input or a protected terminal-mode context file. They can stay in Aven, refresh application state, or request orderly shutdown after successful completion.

See Custom TUI commands for the full configuration schema, JSON input contract, execution modes, tmux example, troubleshooting, and security guidance.

Agent task intake

Natural-language task intake can call an external agent command. Include {prompt} in an argument to pass the generated prompt there. When no argument contains {prompt}, aven writes the prompt to the command’s standard input. Custom system prompts can use {input}, {priorities}, {selected_project}, {inferred_project}, {projects}, and {labels}. A non-empty selected project is authoritative, while the inferred project comes from current-directory routing.

agent:
  task_intake:
    command: "claude"
    args: ["-p", "--no-session-persistence", "--bare", "{prompt}"]
    timeout_seconds: 45

Pi accepts the task-intake prompt through standard input in print mode. This configuration uses Pi’s configured default provider and model:

agent:
  task_intake:
    command: "pi"
    args:
      - --print
      - --no-session
      - --no-tools
      - --no-extensions
      - --no-skills
      - --no-prompt-templates
      - --no-context-files
      - --no-approve
    timeout_seconds: 300

The isolation flags keep task intake independent of project resources and prevent it from creating sessions or invoking tools. Add --provider and --model arguments when task intake should use a specific authenticated model.

Environment overrides

Useful environment overrides include:

Variable	Purpose
AVEN_CONFIG_DIR	Config directory containing config.yaml
AVEN_DB	SQLite database path
AVEN_SYNC_SERVER	Sync server URL
AVEN_NO_UPDATE_CHECK	Disable automatic update checks and TUI notifications when set to 1, true, or yes