@qelos/aidev

aidev turns your tasks into merged code — automatically.

It polls your task manager (ClickUp, Jira, Linear, Monday.com, Notion, Trello, or local markdown files), checks whether tasks are clear, runs Claude, Cursor, or Windsurf to implement them, pushes a branch, and moves the task to review. All without touching your keyboard.

Task  →  AI implements  →  git push  →  "in review"  →  AI resolves code review comments

How it works

Fetch — pulls all tasks tagged with your configured tag from your task provider
Filter — skips done/cancelled tasks and tasks that already have a branch
Clarify — in smart mode, asks the AI if the task description is clear enough; if not, posts a question as a comment (prefixed with [aidev]) and marks the task pending
Wait — pending tasks are re-checked on the next run; if a human replied or the trigger word is found, implementation proceeds with the conversation as context
Implement — checks out a fresh branch (or reuses an existing one), runs your configured AI agent(s), falls back to the next agent if one fails
Ship — commits all changes, pushes the branch, posts a comment with the branch name and a PR link, moves the task to your "in review" status
Review — checks tasks already in review for unresolved PR code review comments; if found, runs an AI agent to fix code or reply to discussion threads

Quick start

npm install -g @qelos/aidev

Navigate to your project and run the interactive setup:

cd my-project
aidev init

The wizard will ask for your task provider credentials, git settings, and preferred AI agents.

Note: aidev init currently supports ClickUp, Jira, Linear, Local, Monday.com, and Trello. For Notion, create .env.aidev manually using .env.aidev.example as a template (see Configuration).

For ClickUp, API keys can be left blank if they are already set as environment variables in your shell. For Jira, Linear, Monday.com, and Trello, the wizard requires credentials to be entered directly — to use shell env vars instead, edit .env.aidev after init and remove the values you want read from your environment.

Once configured:

aidev run

Commands

Command	Description
`aidev init`	Interactive setup — creates `.env.aidev`
`aidev run`	Process open + pending tasks, then check review tasks for unresolved PR comments
`aidev run open`	Only open (non-pending) tasks
`aidev run pending`	Only pending tasks — check for human replies
`aidev run accepted`	Auto-merge PRs for tasks in review with the accepted tag
`aidev run tasks`	Publish all entries in `aidev.tasks.json` and exit (no AI run)
`aidev tasks add`	Add a new entry to `aidev.tasks.json` (interactive)
`aidev tasks ls`	List entries currently queued in `aidev.tasks.json`
`aidev tasks update [id]`	Edit a queued entry (interactive if `id` omitted)
`aidev tasks remove [id]`	Delete a queued entry (interactive if `id` omitted)
`aidev tasks push`	Same as `aidev run tasks` — publish all queued entries and exit
`aidev stop`	Stop any running aidev process in the current directory
`aidev ui`	Launch the local web dashboard (see UI dashboard)
`aidev schedule set`	Interactive cron picker for this directory
`aidev schedule set "<expr>"`	Set a specific cron expression
`aidev schedule set "<expr>" -e <path>`	Set a schedule that uses a custom env file when it fires
`aidev schedule get`	Show the current schedule for this directory
`aidev help`	Show command and config reference

Global flags

Flag	Description
`-e, --env <path>`	Load config from a custom env file instead of `.env.aidev`
`-V, --version`	Print version

Examples

# Use a shared env file for a staging environment
aidev --env /shared/.env.staging run

# Only process tasks that are waiting for a reply
aidev run pending

# Schedule to run every 30 minutes
aidev schedule set "*/30 * * * *"

Concurrency lock

aidev run writes a PID lock file (.aidev.lock) in the current directory when it starts and removes it when it finishes. If a second invocation detects a live process already holding the lock, it logs a warning and exits immediately — preventing two agents from committing to the same branch at the same time.

$ aidev run
[aidev] aidev is already running in this directory (PID 12345). Use "aidev stop" to terminate it.

Use aidev stop to send SIGTERM to the running process and clean up the lock file:

aidev stop

Stale lock files (left behind by a crash) are detected automatically — the next aidev run will overwrite them if the stored PID is no longer alive.

Configuration

Run aidev init for an interactive setup, or create .env.aidev manually using .env.aidev.example as a template.

Global env file (`AIDEV_ENV_EXTEND`)

If you work across multiple projects, you can keep shared settings (API keys, agent list, etc.) in a single global file and reference it from each project's .env.aidev:

# ~/.aidev.global
CLICKUP_API_KEY=pk_...
CLICKUP_TEAM_ID=123456
AGENTS=claude,cursor

# my-project/.env.aidev  — project-specific values override the global ones
AIDEV_ENV_EXTEND=~/.aidev.global
CLICKUP_TAG=my-project

Priority order (highest → lowest):

Shell environment variables (e.g. set in ~/.zshrc) — never overwritten
Local .env.aidev values
AIDEV_ENV_EXTEND file values (global base)

AIDEV_ENV_EXTEND can be set in two ways:

Per-project — add AIDEV_ENV_EXTEND=/path/to/file inside .env.aidev
Shell-wide — export AIDEV_ENV_EXTEND=~/.aidev.global in ~/.zshrc (applies to every project automatically)

aidev init will ask for this path and pre-fill it if the variable is already in your shell environment.

ClickUp

Variable	Default	Description
`CLICKUP_API_KEY`	—	Personal API token — can be set as a shell env var
`CLICKUP_TEAM_ID`	—	Workspace / team ID — can be set as a shell env var
`CLICKUP_TAG`	—	Tasks with this tag will be picked up (set to `*` to match all tasks)
`CLICKUP_PENDING_STATUS`	`pending`	Status name for "waiting for reply"
`CLICKUP_IN_REVIEW_STATUS`	`review`	Status set after implementation
`ASSIGNEE_TAG`	—	Only process tasks assigned to this user (optional)
`THINKING_TAG`	`thinking`	Tasks with this tag are analyzed and broken into sub-tasks before execution
`PLANNING_TAG`	`planning`	Tasks with this tag are split into self-contained sub-tickets pushed back to the provider
`NON_CODE_TAG`	—	Tasks with this tag run without git branching (optional)
`NON_CODE_CLICKUP_TEAM_ID`	same as `CLICKUP_TEAM_ID`	Different workspace for non-code tasks (optional)

Tip: For ClickUp, API keys and tokens are intentionally omitted from .env.aidev if you leave them blank during aidev init — they will be read from your shell environment instead. For Jira, Linear, and Monday.com, the wizard requires these values; to use shell env vars, remove the entries from .env.aidev after init.

Wildcard tag (*): Set CLICKUP_TAG=* (or JIRA_LABEL=* / LINEAR_LABEL=* / TRELLO_LABEL=*) to match all tasks regardless of tags/labels. This is useful when the AI dev has its own dedicated user in the task provider and every task assigned to it should be processed.

Jira

Variable	Default	Description
`JIRA_BASE_URL`	—	Jira instance URL (e.g. `https://mycompany.atlassian.net`)
`JIRA_EMAIL`	—	Email for Jira authentication
`JIRA_API_TOKEN`	—	API token — generate from Atlassian account settings
`JIRA_PROJECT`	—	Project key (e.g. `PROJ`)
`JIRA_LABEL`	—	Issues with this label will be picked up (set to `*` to match all issues)
`JIRA_PENDING_STATUS`	`To Do`	Status name for "waiting for reply"
`JIRA_IN_REVIEW_STATUS`	`In Review`	Status set after implementation
`NON_CODE_JIRA_PROJECT`	same as `JIRA_PROJECT`	Different project for non-code tasks (optional)

Linear

Linear calls them "labels" — the same concept as CLICKUP_TAG / JIRA_LABEL. Tasks created via aidev.tasks.json with tags are mapped to Linear labels on the configured team, and missing labels are created automatically. Default status names align with Linear's standard workflow (Backlog, Todo, In Progress, In Review, Done); if your team renamed those states (e.g. Triage instead of Backlog), aidev also falls back to matching by Linear's underlying state type.

Variable	Default	Description
`LINEAR_API_KEY`	—	Personal API key from Linear Settings → API
`LINEAR_TEAM_ID`	—	Team UUID from your workspace
`LINEAR_LABEL`	—	Issues with this label will be picked up (set to `*` to match all issues)
`LINEAR_PENDING_STATUS`	`Pending`	Status name for "waiting for reply"
`LINEAR_IN_REVIEW_STATUS`	`In Review`	Status set after implementation
`NON_CODE_LINEAR_TEAM_ID`	same as `LINEAR_TEAM_ID`	Different team for non-code tasks (optional)

Monday.com

Variable	Default	Description
`MONDAY_API_TOKEN`	—	API token from monday.com Developer settings
`MONDAY_BOARD_ID`	—	Board ID (from the board URL)
`MONDAY_STATUS_COLUMN_ID`	`status`	Column ID for the status field
`MONDAY_GROUP_ID`	—	Group ID to filter items (optional)

Notion

Variable	Default	Description
`NOTION_API_KEY`	—	Integration token from Notion → Settings → My integrations
`NOTION_DATABASE_ID`	—	Database ID from the database URL (32-char hex)
`NOTION_STATUS_PROPERTY`	`Status`	Name of the status property in the database
`NOTION_PENDING_STATUS`	`pending`	Status value for "waiting for reply"
`NOTION_IN_REVIEW_STATUS`	`review`	Status value set after implementation

Trello

Variable	Default	Description
`TRELLO_API_KEY`	—	Developer API key from trello.com/power-ups/admin
`TRELLO_TOKEN`	—	Auth token generated via Trello's token flow
`TRELLO_BOARD_ID`	—	Board ID from the board URL
`TRELLO_LABEL`	—	Label name on cards to pick up (set to `*` to match all cards assigned to the token user)
`TRELLO_OPEN_LIST`	`To Do`	List name for open/new cards
`TRELLO_PENDING_LIST`	`Blocked`	List name for "waiting for reply"
`TRELLO_IN_PROGRESS_LIST`	`Doing`	List name for cards being worked on
`TRELLO_IN_REVIEW_LIST`	`In Review`	List name for completed cards awaiting review
`TRELLO_OPEN_STATUS`	`open`	Semantic status mapped to the open list
`TRELLO_PENDING_STATUS`	`pending`	Semantic status mapped to the pending list
`TRELLO_IN_REVIEW_STATUS`	`review`	Semantic status mapped to the review list

Git & GitHub

Variable	Default	Description
`GIT_REMOTE`	auto-detected	Remote name — detected via `git remote get-url origin` if unset
`GITHUB_BASE_BRANCH`	`main`	Base branch; new task branches are cut from here
`GITHUB_REPO`	—	`owner/repo` — used to generate PR links in comments

Behaviour

Variable	Default	Description
`AIDEV_ENV_EXTEND`	—	Path to a global env file loaded as the base for this project (see above)
`AGENTS`	`claude,cursor`	Comma-separated list of agents in priority order
`DEV_NOTES_MODE`	`smart`	When to ask for clarification (`smart` or `always`)
`AIDEV_TRIGGER_WORD`	`aidev-continue`	Comment containing this word re-triggers a skipped task
`AIDEV_COMMENT_PREFIX`	`[aidev]`	Custom prefix for all aidev comments posted to task providers
`AIDEV_HOOKS_PATH`	—	Path to a `.ts` or `.js` module that exports hook functions (see Hooks)
`ACCEPTED_TAG`	`accepted`	Tasks in review with this tag are auto-merged (see Auto-merge accepted PRs)
`DONE_STATUS`	auto-detected	Status to set after auto-merging an accepted PR. When unset, aidev picks the first match of `done`, `closed`, `finish`, `success`, `prod` from the board's statuses
`PR_SIGNATURE`	`Automated PR by aidev.`	Custom signature line appended to the PR body
`AIDEV_AUTO_COMPRESS`	`true`	Auto-compress older comments when the prompt grows large. Set to `false` / `0` / `no` to opt out
`AIDEV_COMPRESS_THRESHOLD`	`12000`	Char-length threshold that triggers compression

Hooks

Set AIDEV_HOOKS_PATH in .env.aidev to a path relative to the project directory or an absolute path. aidev init writes .aidev/aidev.hooks.ts and sets AIDEV_HOOKS_PATH=.aidev/aidev.hooks.ts by default.

The module should export an object (or export default) whose properties are optional async functions. Only known hook names are used; anything else is ignored. If a hook throws, the current operation stops (for example the whole run after beforeRun, or conflict resolution after beforeResolveConflicts). If a hook returns an object, it replaces the context for that step (for example append to context.prompt in beforeEachTask and return the updated context).

Hook names

Hook	When	Context notes
`beforeRun` / `afterRun`	Start / end of `aidev run`	`afterRun` includes `processed` and `skipped` counts
`beforeEachTask` / `afterEachTask`	Around each code task implementation	`prompt`, `branchName`, `task`; `afterEachTask` has `success`
`beforeResolveConflicts` / `afterResolveConflicts`	Merge conflict resolution with AI	`conflictFiles`, `prompt`; `afterResolveConflicts` has `resolved`
`beforeNonCodeTask` / `afterNonCodeTask`	Non-code tasks	`afterNonCodeTask` includes agent `output`
`beforeThinkingTask` / `afterThinkingTask`	Thinking-tag tasks (subtask plan)	`beforeThinkingTask` may adjust `subtasks` before steps run
`beforeReviewTask` / `afterReviewTask`	Review tasks with unresolved PR comments	`threads`, `prompt`, `branchName`; `afterReviewTask` has `success`, `resolvedCount`

Second argument: vm

Each hook receives (context, vm). The vm object exposes:

runAI(prompt) — runs the first available configured AI agent
postComment(taskId, text), updateStatus(taskId, status), getComments(taskId) — same family of operations as the task provider
log.info / log.warn / log.error — prefixed hook logging

TypeScript hooks

.ts hook files are loaded at runtime via jiti — no TypeScript compiler or toolchain needed. Just write a plain .ts file with the hook functions and aidev handles the rest.

AI agents

aidev supports multiple AI agents with automatic fallback. The first available agent in the list is used; if it fails, the next one is tried with the previous agent's output as additional context.

Supported agents

Agent	Requires
`antigravity`	Google Antigravity CLI (`agy` or `antigravity`) in PATH — see Antigravity
`claude`	Claude CLI installed and authenticated
`cursor`	Cursor Agent CLI (`agent`) in PATH — see Windows below
`windsurf`	Windsurf installed with CLI available in PATH

Windows: Cursor Agent CLI

On Windows, the Cursor IDE (cursor.exe) is separate from the headless Agent CLI. The runner uses the agent binary. Install it in PowerShell:

irm 'https://cursor.com/install?win32=true' | iex

Then ensure agent is on your PATH and run agent --version to confirm. Without this, the Cursor runner will report as unavailable.

Configure agent order in .env.aidev:

# Claude first, fall back to Cursor
AGENTS=claude,cursor

# Cursor only
AGENTS=cursor

# Cursor first (useful when working locally with a monitor)
AGENTS=cursor,claude

# Claude first, then Windsurf, then Cursor
AGENTS=claude,windsurf,cursor

# Antigravity first, then Claude
AGENTS=antigravity,claude

# Windsurf only
AGENTS=windsurf

Trigger word & re-processing

aidev prefixes every comment it posts with [aidev] (configurable via AIDEV_COMMENT_PREFIX). This lets it distinguish its own comments from human replies when deciding whether to re-process a task.

A task is normally skipped when:

A remote branch already exists for it, or
It is pending and no human has replied yet

To force aidev to pick the task up again, post a comment containing the trigger word (default: aidev-continue). aidev will reuse the existing branch and continue implementation from where it left off.

# Customise the trigger word in .env.aidev
AIDEV_TRIGGER_WORD=please-retry

The trigger word match is case-insensitive, so aidev-continue, AIDEV-CONTINUE, and Aidev-Continue all work.

For pending tasks, a regular human reply (any comment without the configured prefix) also triggers re-processing — the trigger word is an additional explicit mechanism.

# Customise the comment prefix in .env.aidev
AIDEV_COMMENT_PREFIX=[mybot]

Auto-compress

For long-running tasks with many comments, the combined prompt (description + conversation history + review threads) can grow past the AI agent's effective context window. When the assembled context exceeds AIDEV_COMPRESS_THRESHOLD characters (default 12000), aidev summarises the older comments via the configured AI agent and keeps only the latest comment verbatim — so the agent always sees the user's most recent intent without ambiguity.

Compressed summaries are cached under .aidev/sessions/<taskId>.json and reused across runs; new comments invalidate the cache and trigger a re-summarisation of the delta. The directory is added to .gitignore automatically.

This is on by default. To opt out:

# In .env.aidev
AIDEV_AUTO_COMPRESS=false

# Or raise the threshold instead of disabling
AIDEV_COMPRESS_THRESHOLD=24000

Non-code tasks

Tasks tagged with NON_CODE_TAG are executed without git branching — no checkout, commit, push, or PR creation. The AI agent runs the task directly in the current working directory.

This is useful for:

Research or investigation tasks
Documentation updates that don't go through PR review
Running scripts or commands
Any task where you want the AI to act without creating a branch

# In .env.aidev
NON_CODE_TAG=non-code

# Optionally use a different ClickUp team for non-code tasks
NON_CODE_CLICKUP_TEAM_ID=987654

# Or a different Jira project
NON_CODE_JIRA_PROJECT=OPS

Non-code tasks follow the same lifecycle as regular tasks (clarification → implementation → review), except the implementation step skips all git operations. After completion, the task status is moved to your configured "in review" status.

If NON_CODE_TAG is not configured, non-code task processing is disabled entirely.

Code review resolution

When aidev run executes, it also checks tasks in review status for unresolved PR code review comments. If any actionable threads are found, an AI agent is run to address them — either by fixing the code or replying to discussion comments.

How it works:

Fetches all tasks in your configured "in review" status
For each task, finds the associated PR by branch name (via gh CLI)
Fetches unresolved review threads from the PR
Filters out threads where the last comment is from aidev itself (to avoid re-processing)
Runs an AI agent to address the remaining threads — code fixes are committed and pushed, discussion replies are posted directly on the thread
Resolved threads are marked as resolved on GitHub

This runs automatically as part of every aidev run (after processing open/pending tasks). No additional configuration is needed beyond having gh CLI installed and authenticated.

Prerequisites: The GitHub CLI must be installed and authenticated (gh auth login). If gh is not available, review task processing is silently skipped.

Auto-merge accepted PRs

When a task has been reviewed and is ready to merge, tag it with accepted (the default — override via ACCEPTED_TAG). On the next run, aidev will automatically merge the PR via the GitHub CLI (gh), update the task status, and sync your local main branch.

This feature works out of the box whenever the gh CLI is installed and authenticated.

# In .env.aidev (both optional)
# ACCEPTED_TAG=accepted   # the tag aidev looks for on review tasks (default: accepted)
# DONE_STATUS=done        # status to apply after merge — auto-detected when omitted

How it works:

Finds all tasks in your "in review" status that have the accepted tag (accepted by default)
For each task: merges the PR with squash and deletes the remote branch (gh pr merge --squash --delete-branch)
Updates the task status to DONE_STATUS. When unset, aidev probes the board for one of done, closed, finish, success, prod and uses the first match
Checks out the base branch and pulls the latest changes

Run it manually:

aidev run accepted

Automatic mode: Whenever gh is available, accepted PRs are also auto-merged at the end of every aidev run.

Prerequisites: The GitHub CLI must be installed and authenticated (gh auth login). aidev init will prompt you for these settings if it detects gh on your PATH.

Dev notes mode

Controls when aidev asks the task provider for clarification before implementing.

Mode	Behaviour
`smart`	Asks the AI whether the task description is clear enough. Only posts a clarification question if it's ambiguous.
`always`	Always posts "any dev notes?" before implementing every task.

When a question is posted, the task is moved to the configured pending status (e.g. CLICKUP_PENDING_STATUS, JIRA_PENDING_STATUS, etc.). On the next run, aidev checks whether a human has replied and, if so, includes the reply as context for the AI.

Local tasks file (`aidev.tasks.json`)

aidev.tasks.json is an outbound queue — a JSON file that sits at the root of your project and holds task templates that aidev will publish to your configured provider (ClickUp, Jira, Linear, etc.). It is the opposite direction from the Local provider: the local provider stores tasks on disk, while aidev.tasks.json pushes tasks to a remote provider.

Typical uses:

Recurring tasks — with a cron expression, an entry publishes a fresh task on every matching tick (daily standup reminders, weekly reviews, monthly housekeeping).
Staged work — queue a batch of tasks in a commit so they appear in the provider together when aidev next runs.
AI-authored tasks — another AI agent or script can append entries to the file; aidev will pick them up and create real tickets.

The file is added to .gitignore by aidev init — each developer or automation environment maintains their own queue.

File format

aidev.tasks.json is a JSON array of task entries. Each entry has the shape:

interface LocalTask {
  id: string;              // UUID — generated automatically by "aidev tasks add"
  title: string;           // required — task title on the remote provider
  description: string;     // task body / description
  type: 'code' | 'non-code'; // routes to the non-code provider when set to 'non-code'
  priority?: number;       // 1=urgent, 2=high, 3=normal, 4=low
  assignee?: string;       // currently informational (reserved for future use)
  dueDate?: string;        // ISO date, e.g. "2026-05-01"
  tags?: string[];         // extra tags appended to the provider-configured tag
  listId?: string;         // override provider list / project ID for this task only
  cron?: string;           // 5-field cron — if set, the task is re-published on every tick
  lastPushedAt?: number;   // epoch ms of the last successful push (managed by aidev for cron entries)
}

Example (aidev.tasks.json):

[
  {
    "id": "7f3a9c2d-5b1e-4a6f-9d8c-1e2f3a4b5c6d",
    "title": "Daily standup notes",
    "description": "Post yesterday / today / blockers to the team channel.",
    "type": "non-code",
    "priority": 3,
    "tags": ["standup"],
    "cron": "0 9 * * 1-5"
  },
  {
    "id": "2b8e1f7a-4c9d-4e5a-8b6c-9f1e2d3c4b5a",
    "title": "Upgrade dependencies",
    "description": "Run `npm outdated`, bump minor/patch versions, verify tests pass.",
    "type": "code",
    "priority": 2,
    "tags": ["maintenance"]
  }
]

Lifecycle

Every aidev run (regardless of filter) begins by reading aidev.tasks.json and attempting to publish each entry via the configured provider's createTask API.
One-shot entries (no cron field) are removed from the file after a successful push — they become a real ticket and won't be duplicated on the next run.
Cron entries remain in the file. lastPushedAt is updated on each successful push; on the next run, aidev checks whether the cron has fired at least once since lastPushedAt before republishing. A fresh entry with a cron fires on the first run that matches.
Failures are logged and the entry is kept — the next run retries.

Routing

type: 'code' → published with the code tag (CLICKUP_TAG / JIRA_LABEL / LINEAR_LABEL, etc.) to the primary provider.
type: 'non-code' → published with NON_CODE_TAG to the non-code provider (a separate team / project if NON_CODE_CLICKUP_TEAM_ID, NON_CODE_JIRA_PROJECT, or NON_CODE_LINEAR_TEAM_ID is configured, otherwise the primary).
Per-task tags are appended to the resolved default tag.
Per-task listId overrides the provider-default list / project for that single task.

Managing entries

Use the built-in commands rather than hand-editing JSON (although hand-editing is fine — the file is plain JSON):

aidev tasks add              # interactive prompt: title, description, type, priority, due date, tags, list, cron
aidev tasks ls               # table of queued entries
aidev tasks update [id]      # edit an entry by table ID (interactive picker if no id)
aidev tasks remove [id]      # delete an entry by table ID (interactive picker if no id)
aidev tasks push             # publish everything now (same as "aidev run tasks") — useful for dry-running or in scripts

aidev tasks push and aidev run tasks do the same thing: they only process aidev.tasks.json and exit without pulling tasks from the provider or invoking the AI. This is useful when you want to decouple queue publishing from the main AI loop — for example, running aidev tasks push from a separate cron entry or CI job.

Scheduling

aidev can run on a cron schedule, one entry per project directory.

# Interactive picker
aidev schedule set

# Or pass an expression directly
aidev schedule set "*/15 * * * *"

# Run a schedule against a custom env file (so the scheduled run uses
# that config — useful when several env files live alongside one repo)
aidev schedule set "*/15 * * * *" -e /path/to/custom/.env.aidev

# Check what's scheduled for the current directory
aidev schedule get

The -e <path> option is baked into the scheduled entry itself (the cron line on Linux, the LaunchAgent plist on macOS, or the Task Scheduler /tr command on Windows), so each run will pick up the right env file without relying on the shell environment at firing time.

Preset options (interactive picker)

Option	Expression
Every 15 minutes	`/15 * * *`
Every 30 minutes	`/30 * * *`
Every hour	`0 * * * *`
Every 5 hours	`0 /5 * *`
Every day at 8am	`0 8 * * *`

Each directory gets its own cron entry identified by a # aidev-cwd:/path marker — running schedule set again replaces the existing entry rather than adding a duplicate.

macOS: Full Disk Access required

On macOS (Ventura and later), cron jobs are silently blocked unless /usr/sbin/cron has Full Disk Access:

Open System Settings → Privacy & Security → Full Disk Access
Click + and add /usr/sbin/cron
Re-run aidev schedule set to apply your schedule

Without this, cron will appear to be configured but jobs will never fire.

Logging

Every run appends to aidev.log in your project directory:

────────────────────────────────────────────────────────────
2026-03-06T08:00:00.000Z [run] started
────────────────────────────────────────────────────────────
2026-03-06T08:00:00.120Z [info] Fetching tasks (filter: all)...
2026-03-06T08:00:01.340Z [task] [abc123] "Fix login flow" (status: open)
2026-03-06T08:00:12.780Z [info] Running claude...
2026-03-06T08:00:45.210Z [success] Task implemented: branch abc123/fix-login-flow pushed
2026-03-06T08:00:45.890Z [success] Done. Processed: 1, Skipped: 3

ANSI colour codes are stripped so the file stays readable in any editor or tail -f. aidev.log is added to .gitignore automatically by aidev init.

To write the log somewhere else, set AIDEV_LOG_PATH to an absolute, relative, or ~/-prefixed path that includes the file name (not just the folder). Relative paths are resolved against the project cwd and missing parent directories are created on first write.

AIDEV_LOG_PATH=logs/aidev.log         # → <cwd>/logs/aidev.log
AIDEV_LOG_PATH=/var/log/aidev.log     # absolute
AIDEV_LOG_PATH=~/aidev/run.log        # under your home directory

Providers

Provider	Status	`aidev init` support
ClickUp	✅ Implemented	✅ Interactive wizard
Jira	✅ Implemented	✅ Interactive wizard
Linear	✅ Implemented	✅ Interactive wizard
Monday.com	✅ Implemented	✅ Interactive wizard
Local	✅ Implemented	✅ Interactive wizard
Notion	✅ Implemented	Manual `.env.aidev` config
Trello	✅ Implemented	✅ Interactive wizard

Notion: This provider is fully functional but not yet included in the aidev init wizard. To use it, set PROVIDER=notion in .env.aidev and fill in the required variables from the Configuration section above.

The TaskProvider interface makes it straightforward to add new providers. See CONTRIBUTING.md.

Local provider

Set PROVIDER=local in .env.aidev to manage tasks entirely via local markdown files — no external API needed.

aidev init   # choose "local" when prompted for provider

Tasks live in .aidev/tasks/ under status folders:

.aidev/tasks/
  open/          # new tasks ready for implementation
  pending/       # waiting for human reply
  progress/      # currently being implemented
  review/        # implementation complete, awaiting review
  done/          # finished

Task file format (e.g. .aidev/tasks/open/a1b2c3d4-fix-login-bug.md):

---
title: Fix login page bug
priority: 2
assignee: david
estimated: 2h
tags: frontend, auth
created: 2026-03-12T10:00:00.000Z
---

The login form should redirect users to the dashboard after successful authentication.

The filename must start with a short ID (hex characters) followed by a dash and a slug. The YAML frontmatter carries task metadata; everything after --- is the task description.

Code vs non-code tasks

By default, local tasks are treated as code tasks — aidev creates a git branch, runs the AI agent, commits, pushes, and opens a PR.

To mark a task as non-code (research, docs, investigation — no git branching), add type: non-code to the frontmatter:

---
title: Compare OAuth2 providers
type: non-code
tags: research
---

Evaluate Auth0, Clerk, and Supabase Auth. Write a recommendation.

Non-code tasks follow the same lifecycle but skip all git operations. The AI response is posted as a session comment instead of a PR.

Session file (comments) — .aidev/tasks/open/a1b2c3d4-fix-login-bug.session.md:

<!-- aidev session log — append your comments below using "## your-name" as header -->

---

## aidev — 2026-03-12T10:05:00.000Z

[aidev] Starting implementation on branch `a1b2c3d4/fix-login-bug`

---

## david — 2026-03-12T10:10:00.000Z

Please use the new auth API endpoint for this.

To add a comment, append a --- separator followed by a ## your-name header and your message. aidev parses these entries automatically and uses them as conversation context, just like ClickUp/Jira comments.

Downloaded task attachments are stored in .aidev/assets/<task-id>/, and aidev init adds .aidev/assets/ to .gitignore automatically.

UI dashboard

aidev ui starts a local Nuxt dashboard for managing .env.aidev, browsing the log file, working with provider tasks, and triggering aidev run from a browser. The server binds to 127.0.0.1 only and requires a one-shot token printed when the command starts — nothing is exposed beyond your machine.

Run it:

aidev ui                 # http://127.0.0.1:19422
aidev ui --port 19500    # pick a different port

If you installed aidev from npm (e.g. npm install -g @qelos/aidev), the prebuilt Nuxt output is included in the package and aidev ui serves it directly — no extra setup. If you're hacking on the dashboard from a source checkout, install dev deps once (cd ui && npm install) and aidev ui will run Nuxt in dev mode with hot reload; pass --prod to serve the built output instead (after cd ui && npm run build).

The command prints a http://127.0.0.1:<port>/login?token=<token> URL — click it to authenticate. The token is regenerated on every launch and stored in the browser's localStorage for the session.

See ui/docs/handover/ for the per-screen design notes used when extending the dashboard.

Contributing

Contributions are welcome — new providers, new AI runners, bug fixes, and docs improvements.

See CONTRIBUTING.md for the full guide.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 176 Commits
.cursor		.cursor
.github/workflows		.github/workflows
scripts		scripts
src		src
ui		ui
.env.aidev.example		.env.aidev.example
.gitignore		.gitignore
.npmignore		.npmignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

@qelos/aidev

Table of Contents

How it works

Quick start

Commands

Global flags

Concurrency lock

Configuration

Global env file (AIDEV_ENV_EXTEND)

ClickUp

Jira

Linear

Monday.com

Notion

Trello

Git & GitHub

Behaviour

Hooks

AI agents

Windows: Cursor Agent CLI

Trigger word & re-processing

Auto-compress

Non-code tasks

Code review resolution

Auto-merge accepted PRs

Dev notes mode

Local tasks file (aidev.tasks.json)

File format

Lifecycle

Routing

Managing entries

Scheduling

macOS: Full Disk Access required

Logging

Providers

Local provider

Code vs non-code tasks

UI dashboard

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Global env file (`AIDEV_ENV_EXTEND`)

Local tasks file (`aidev.tasks.json`)

Packages