> your AI agent picks dependencies from memory; give it dated facts — try starlog.dev ↗ vet your agent's deps ↗ vibe-coding is fine. vibe-importing isn’t. — try starlog.dev ↗ vibe-importing isn’t fine ↗ your agent has never seen your private packages — try starlog.dev ↗ facts for private packages ↗ a linter for the dependencies your AI agent picks — try starlog.dev ↗ a linter for agent deps ↗ whois is redacted, cdns mask the rest — get the real operator — try whoisgeni.us ↗ who really runs that domain ↗ domain attribution that shows its work — full evidence chain — try whoisgeni.us ↗ domain intel w/ evidence ↗

← Back to Articles

itsaplan: The Issue Tracker Where AI Agents Are Team Members, Not Features

[ View on GitHub ]

itsaplan: The Issue Tracker Where AI Agents Are Team Members, Not Features

Hook

Most project management tools treat AI as a fancy autocomplete for comments. itsaplan gives agents their own seat at the sprint planning table—they get assigned issues, own work items, and execute code on your machine while you sleep.

Context

Linear perfected the fast, opinionated issue tracker. Plane brought that experience to the self-hosted world. But both treat AI as auxiliary intelligence—summarization bots, triage assistants, and glorified search engines. No mainstream project management tool has solved the fundamental problem: how do you let an AI agent actually do the work?

The problem isn't technical sophistication. Claude can write production code. GitHub Copilot can implement entire features. But our project management tools still relegate AI to the comments section. You can't assign an issue to an agent and expect it to open a PR. You can't have an agent participate in planning poker or update its own estimates. The tooling assumes humans do the work and AI watches from the sidelines. itsaplan tears down that assumption by making agents structurally identical to human team members—they have permissions, own issues, and ship code. The architecture that enables this is more interesting than the feature itself.

Technical Insight

The agent system works through two parallel tracks: internal agents that run on your instance, and external agents that run on developer machines. Internal agents use the Mastra framework and live in your deployment. Mention @agent in an issue comment or assign an issue to an agent, and the backend spawns a job that gives the agent read/write access to your project via tool calls:

// Internal agent tool definition (simplified from codebase)
const updateIssue = {
  name: 'update_issue',
  description: 'Modify an existing issue',
  parameters: z.object({
    issueId: z.string(),
    title: z.string().optional(),
    description: z.string().optional(),
    status: z.enum(['backlog', 'todo', 'in_progress', 'done']).optional(),
    assigneeId: z.string().optional(),
  }),
  execute: async ({ issueId, ...updates }) => {
    const issue = await db.issue.update({
      where: { id: issueId },
      data: updates,
    });
    await webhooks.trigger('issue.updated', issue);
    return issue;
  },
};

Agents aren't calling a privileged API—they're using the same Drizzle ORM transactions as the REST endpoints. Permission checks run before tool execution, so agents in a project can only modify issues they're allowed to see. The webhook trigger at the end means agent actions flow through the same event pipeline as human actions, keeping audit logs and external integrations consistent.

The external agent architecture is where things get genuinely novel. Instead of embedding AI execution in your server (with cold starts, credential management, and timeout limits), itsaplan inverts the control flow. You run an agent runner daemon on your development machine:

npm install -g @itsaplan/agent-runner
itsaplan-runner --api-url https://yourinstance.com --token YOUR_TOKEN

The runner polls the API for tasks assigned to external agents, executes them using CLI tools already on your machine (Claude Code, GitHub Copilot CLI, or local scripts), and streams responses back. The instance tracks task state but never sees your API keys or codebase. When an external agent gets assigned an issue, the backend creates a task, the runner picks it up, shells out to claude-code --prompt "Fix issue #123", captures stdout/stderr, and posts the result as an issue comment with any generated code as an attachment.

This solves three problems simultaneously: credential isolation (your OpenAI API key stays on localhost), persistent context (the agent runs in your working directory with full repo history), and execution environment (agents have access to your Docker daemon, test suites, and build tools without containerization gymnastics).

The Model Context Protocol (MCP) server takes this further by exposing the entire issue tracker as a tool set for external LLMs. Run the MCP server in your Claude Desktop config, and suddenly Claude can query your backlog, create issues, and link them to PRs—all through natural language:

// MCP server configuration for Claude Desktop
{
  "mcpServers": {
    "itsaplan": {
      "command": "npx",
      "args": ["-y", "@itsaplan/mcp-server"],
      "env": {
        "ITSAPLAN_API_URL": "https://yourinstance.com",
        "ITSAPLAN_TOKEN": "your_token_here"
      }
    }
  }
}

Now you can tell Claude "Create an issue for the login bug we discussed and assign it to the auth-agent" and it happens. The MCP server isn't read-only telemetry—it's a writable control plane.

The custom field system uses a pragmatic JSONB approach that avoids schema migrations. Each project defines field schemas (text, number, date, select) stored in a custom_fields table, and issue values live in a JSONB column with validation at the application layer:

// Custom field values stored as JSONB (simplified)
interface Issue {
  id: string;
  title: string;
  customFields: Record<string, unknown>; // JSONB column
}

// Validation happens in the API layer
const fieldSchema = await getProjectFieldSchema(projectId);
for (const [key, value] of Object.entries(customFields)) {
  const field = fieldSchema[key];
  if (field.type === 'number' && typeof value !== 'number') {
    throw new ValidationError(`${key} must be a number`);
  }
}

This trades query performance for deployment simplicity—you can add custom fields without ALTER TABLE commands or migrations—but you can't efficiently filter or join on custom field values. The PostgreSQL JSONB operators help (WHERE custom_fields @> '{"priority": "high"}'), but you're still doing full table scans for complex queries.

Gotcha

The external agent runner is operationally fragile. It's a long-running Node.js process on your laptop that dies when your machine sleeps, your VPN reconnects, or you restart for system updates. The codebase shows no persistent queue or resume logic—if the runner crashes mid-task, the work is lost. You'll need to wrap it in systemd or launchd with restart policies, and even then, you're one Docker Desktop update away from mysterious failures.

The JSONB custom field approach hits real walls at scale. You can't create database indexes on JSONB values without GIN indexes on specific paths, which means no query planner optimization for "show me all issues where custom field X equals Y." Small teams won't notice, but at 10,000+ issues, filter and search operations will crawl. The tradeoff makes sense for a three-month-old project prioritizing iteration speed over query performance, but you'll eventually need to migrate to a proper EAV table or a relational schema with nullable columns. The lack of real-time collaboration is a showstopper for teams that pair program or mob on planning. Two people editing the same issue description simultaneously results in last-write-wins data loss. No conflict resolution, no operational transforms, no awareness of concurrent edits—just a race condition with an apology message after someone's work disappears.

Verdict

Use if: you want AI agents that actually ship code, not just summarize comments; you need pull request linking across non-GitHub forges (GitLab, Gitea, Bitbucket); you're comfortable running infrastructure and accepting breaking changes in exchange for novel capabilities; you need MCP server integration for external LLM control; or the AGPL license aligns with your open-source philosophy. Skip if: you need real-time collaboration for synchronous work (use Linear instead); you can't self-host and need a SaaS option (try Height); you're building on top of it and can't navigate AGPL licensing (talk to them about commercial terms); you need battle-tested stability over experimental AI features (Plane is safer); or you expect agents to work without running a daemon on developer machines (no current tool solves this well, but itsaplan's external runner is more fragile than most).