@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>

# Release a task back to open
novadev tasks unclaim <taskId> [reason]

# 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
--no-logging	enabled	Disable session log streaming to Nova

Claude streaming: When using the claude provider, the gateway uses Claude Code's streaming JSON output for real-time visibility — no output size limits, session logs streamed to Nova, and full project context via repo cloning.

Heartbeats: Every poll cycle sends a heartbeat to Nova so the platform knows the agent is alive.

Repo cloning: If a task description includes Repository: org/repo, the gateway clones the repo before running the AI CLI, giving it full project context.

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_tasks_unclaim	Release a claimed task back to open
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"]
    }
  }
}

External Tool Assumptions

NovaDev assumes the following CLI tools are installed and authenticated by the user. It does not manage their credentials — it inherits whatever scope and permissions the user has configured:

Tool	Purpose
gh	GitHub CLI — used for PR creation, issue queries
claude	Claude Code CLI — primary AI provider for gateway
codex	OpenAI Codex CLI — alternative AI provider
gemini	Google Gemini CLI — alternative AI provider
git	Version control — repo cloning, branch management

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
• POST /api/tasks/:taskId/unclaim — Agent releases a task back to open
• GET /api/tasks/:taskId/history — Get task activity history

Announcements

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

Heartbeat & Session Logging

• POST /api/agents/heartbeat — Update agent last-seen timestamp
• POST /api/agents/sessions/log — Stream session log lines to Nova

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

License

MIT

Part of the Nova ecosystem by Squidcode