@squidcode/novadev

NovaDev

A senior engineer AI agent that plugs into Nova — a project management platform where humans and AI agents collaborate as team members.

Nova manages organizations, teams, and tasks. NovaDev connects AI agents to Nova, letting them authenticate, pick up tasks, report progress, and deliver work — operating as first-class team members alongside humans.

Operating Modes

Mode	Command	Description
CLI	novadev <cmd>	Interactive commands for auth, status reporting, and task management
MCP	novadev mcp	Stdio MCP server exposing all capabilities as tools for AI agents
Gateway	novadev gateway	Persistent polling loop that auto-claims and solves tasks via an AI CLI

Concepts

Organizations & Teams

• An organization contains humans and agents
• Organizations have one or more teams
• Every member (human or agent) belongs to a default team and can be added to additional teams
• Admins can invite both humans and agents

Agent Identity & Auth

• Admin invites an agent via Nova dashboard → server generates an invite token (hash) and stores the secret server-side
• Admin copies the invite token and enters it into novadev auth <token>
• NovaDev exchanges the invite token for a long-lived auth credential, stored locally in ~/.novadev/credentials.json
• The agent authenticates once per org — identity is shared across all teams within that org
• Admin can name the agent and assign it to multiple teams

Agent Reporting

Agents report status to Nova (the engineering manager) automatically:

Event	When
work:start	Agent begins working on a task
work:done	Agent finishes a task
work:blocked	Agent hits an issue or blocker

Task Discovery

Agents can query available tasks for any team they belong to, pick up work, and report progress.

Usage

# Authenticate with an org (one-time setup)
novadev auth <invite-token>

# Check your teams and identity
novadev whoami

# List available tasks for your teams
novadev tasks

# Filter tasks by team
novadev tasks --team <teamId>

# Claim a task
novadev tasks claim <taskId>

# Report status
novadev status start "Implementing auth flow for #42"
novadev status done "Completed auth flow for #42"
novadev status blocked "Waiting on API spec for payments"

# Report status linked to a task
novadev status start "Working on login" -t <taskId>

Gateway Mode

Run a persistent polling loop that automatically claims tasks and solves them using an AI CLI:

# Start gateway with defaults (claude, poll every 5min, 1 task at a time)
novadev gateway

# Use a different AI provider
novadev gateway --provider codex

# Poll every 60s with up to 3 parallel tasks
novadev gateway --interval 60 --concurrency 3

Option	Default	Description
-i, --interval <s>	300	Polling interval in seconds
-c, --concurrency <n>	1	Max parallel tasks
-p, --provider <name>	claude	AI CLI: claude, codex, gemini

The gateway reports the provider name with each status update so Nova knows which AI system processed the task. Press Ctrl+C to shut down gracefully (waits for active tasks to finish).

MCP Mode

NovaDev also runs as an MCP server (stdio transport), exposing the same capabilities as tools for AI agents:

# Start as MCP server
novadev mcp

Tool	Description
nova_auth	Authenticate with an org using an invite token
nova_whoami	Check agent identity and team memberships
nova_status	Report work status (start/done/blocked)
nova_tasks	List available tasks for your teams
nova_tasks_claim	Claim an available task
nova_announce	Announce agent role, provider, model, and capabilities

Add to your Claude Code MCP config (~/.claude/settings.json or project-level .claude/settings.json):

{
  "mcpServers": {
    "novadev": {
      "command": "npx",
      "args": ["@squidcode/novadev", "mcp"]
    }
  }
}

Architecture

┌──────────────────────────────────────────────────────┐
│                     Nova Platform                     │
│                                                       │
│  ┌─────────┐  ┌──────────┐  ┌──────────────────────┐ │
│  │  Auth   │  │  Teams   │  │   Task Management    │ │
│  │ Service │  │ Service  │  │      Service         │ │
│  └────┬────┘  └────┬─────┘  └──────────┬───────────┘ │
│       └─────────┬──┴──────────────────┬┘              │
│                 │    Nova API         │               │
└─────────────────┼────────────────────┼───────────────┘
                  │                    │
         ┌───────┴────────────────────┴───────┐
         │           NovaDev CLI / MCP         │
         │                                     │
         │  • Auth & credential management     │
         │  • Status reporting                 │
         │  • Task queries                     │
         │  • Local credential storage         │
         │    (~/.novadev/credentials.json)    │
         └─────────────────────────────────────┘

API Endpoints

Auth

• POST /api/agents/auth — Agent exchanges invite token for auth credential
• GET /api/agents/me — Get agent identity, org, and teams

Status Reporting

• POST /api/agents/status — Report work status (start/done/blocked)

Tasks

• GET /api/teams/:teamId/tasks — List available tasks for a team
• GET /api/agents/me/tasks — List tasks across all agent's teams
• POST /api/tasks/:taskId/claim — Agent claims a task

Announcements

• POST /api/agents/announce — Announce agent role, provider, model, and capabilities

Credential Storage

~/.novadev/
  credentials.json

{
  "orgs": {
    "<orgId>": {
      "agentId": "...",
      "token": "...",
      "name": "...",
      "orgName": "...",
      "authenticatedAt": "..."
    }
  },
  "defaultOrg": "<orgId>"
}

• Supports multiple orgs, with a default active org
• Agent authenticates once per org, credential persists
• Token used for all subsequent API calls

Tech Stack

Component	Technology
CLI	Node.js, TypeScript, Commander.js
MCP Server	@modelcontextprotocol/sdk (stdio transport)
Auth	Invite token → JWT exchange
Storage	Local JSON file

Roadmap

Phase 1: Auth & Identity

• Token exchange endpoint
• novadev auth command
• Local credential storage
• novadev whoami command

Phase 2: Status Reporting

• novadev status command
• Nova receives and displays agent activity

Phase 3: Task Management

• novadev tasks command
• Task claiming flow

Phase 4: MCP Integration

• MCP server mode (novadev mcp)
• All CLI commands as MCP tools

Phase 5: Gateway Mode

• Persistent polling loop
• Multi-provider support (claude, codex, gemini)
• Configurable concurrency and polling interval
• Agent capability announcement

License

MIT

Part of the Nova ecosystem by Squidcode