@contextgraph/agent

@contextgraph/agent

Autonomous agent for contextgraph action execution.

Installation

No installation required! Use npx to run commands directly:

npx @contextgraph/agent <command>

Or install globally for convenience:

npm install -g @contextgraph/agent

Prerequisites

• Node.js 18 or higher
• Active contextgraph.dev account

Quick Start

Option 1: Interactive Authentication

• Authenticate with contextgraph.dev:

npx @contextgraph/agent auth

• Run the agent:

npx @contextgraph/agent run

Option 2: API Token (CI/CD & Cloud Deployments)

For automated environments, use an API token:

export CONTEXTGRAPH_API_TOKEN="your-api-token"
npx @contextgraph/agent run

Get your API token from https://contextgraph.dev/settings/tokens

Commands

auth

Authenticate with contextgraph.dev using OAuth:

npx @contextgraph/agent auth

Opens your browser to complete authentication. Credentials are securely stored in ~/.contextgraph/.

whoami

Check your current authentication status:

npx @contextgraph/agent whoami

Shows your user ID and token expiration.

run <action-id>

Run the autonomous agent loop:

npx @contextgraph/agent run <action-id>

The agent will:

• Fetch the action tree
• Find the next unprepared/incomplete leaf action
• Prepare it (if needed) - assess if it should be broken down
• Execute it - implement the work using Claude
• Repeat until all actions are complete

prepare <action-id>

Prepare a single action:

npx @contextgraph/agent prepare <action-id>

Spawns Claude to assess whether the action should be broken down into child actions or is ready to execute.

execute <action-id>

Execute a single prepared action:

npx @contextgraph/agent execute <action-id>

Spawns Claude to implement the action and mark it complete.

How It Works

The agent implements a prepare/execute workflow:

Prepare Phase:

• Fetches action details including parent chain, siblings, and dependencies
• Analyzes whether the action is atomic or should be broken down
• If complex, creates child actions with proper dependencies
• Marks the action as prepared

Execute Phase:

• Implements the work described in the action
• Runs tests and builds to verify changes
• Commits and pushes changes to the appropriate branch
• Marks the action as complete with detailed completion context

Autonomous Loop:

• The run command traverses the action tree depth-first
• Automatically prepares and executes actions in dependency order
• Continues until all actions in the tree are complete

The agent integrates with contextgraph.dev's MCP server to:

• Fetch action details and relationships
• Create and update actions
• Track completion context and learnings

Troubleshooting

Authentication failures

If authentication fails or tokens expire:

npx @contextgraph/agent auth

This will open a new browser session to re-authenticate.

Expired credentials

Tokens expire after a period of time. Re-authenticate with:

npx @contextgraph/agent whoami  # Check expiration
npx @contextgraph/agent auth    # Re-authenticate if expired

Network errors

Ensure you have internet connectivity and can reach:

• https://www.contextgraph.dev (API endpoint)
• https://contextgraph.dev (authentication)

Links

• contextgraph.dev - Main platform
• GitHub Repository - Source code and issues
• Issue Tracker - Report bugs or request features

Configuration

Credentials

The agent supports two authentication methods:

1. Interactive OAuth (Default)

Credentials are stored in ~/.contextgraph/credentials.json after running contextgraph-agent auth.

2. API Token (Environment Variable)

Set the CONTEXTGRAPH_API_TOKEN environment variable for automated deployments:

export CONTEXTGRAPH_API_TOKEN="your-api-token"

This is ideal for:

• CI/CD pipelines (GitHub Actions, GitLab CI, etc.)
• Cloud worker deployments (AWS Lambda, Modal, etc.)
• Docker containers
• Any automated environment where interactive login isn't possible

API tokens take precedence over file-based credentials when both are present.

Worker Polling

The worker uses exponential backoff when no work is available to prevent server overload. Configure polling behavior with environment variables:

• WORKER_INITIAL_POLL_INTERVAL - Initial polling interval in milliseconds (default: 2000 / 2 seconds)
• WORKER_MAX_POLL_INTERVAL - Maximum polling interval in milliseconds (default: 30000 / 30 seconds)

When no work is available, the worker waits before polling again. The wait time increases exponentially (1.5x multiplier) up to the maximum interval. On successful claim, the interval resets to the initial value.

Example:

# Poll more frequently (every 1 second initially, up to 15 seconds max)
WORKER_INITIAL_POLL_INTERVAL=1000 WORKER_MAX_POLL_INTERVAL=15000 npx @contextgraph/agent run <action-id>

Claude Agent SDK

The agent uses the Claude Agent SDK for reliable, high-performance execution of actions. The SDK provides:

• Consistent error handling and recovery
• Direct API integration without CLI dependencies
• Better timeout and cancellation control
• Structured message parsing and formatting

SDK Authentication

The Claude Agent SDK requires Anthropic API credentials. Set the ANTHROPIC_API_KEY environment variable:

export ANTHROPIC_API_KEY="your-anthropic-api-key"

This is required for:

• Worker agent execution
• Autonomous action processing
• Any command that spawns Claude for prepare/execute operations

Generating Long-Lived Anthropic Tokens:

For CI/CD pipelines, cloud deployments, and unattended worker execution, you'll need a long-lived Anthropic API key:

• Visit the Anthropic Console API Keys page
• Click "Create Key" to generate a new API key
• Give it a descriptive name (e.g., "Production Worker" or "CI/CD Pipeline")
• Copy the key immediately - it won't be shown again
• Store it securely in your environment or secrets manager

Security Best Practices:

• Never commit API keys to version control
• Use environment variables or secrets management systems (AWS Secrets Manager, GitHub Secrets, etc.)
• Rotate keys periodically
• Use separate keys for different environments (development, staging, production)
• Revoke compromised keys immediately from the Anthropic Console

For local development, you can set the key in your shell profile (~/.bashrc, ~/.zshrc) or use a .env file (with proper .gitignore configuration).

cg - ContextGraph Action CLI

The cg CLI provides command-line access to the ContextGraph action graph with full parity to the MCP server tools. It's designed for agent execution workflows, outputting JSON that can be piped through jq or grep for filtering.

Installation

The cg binary is included when you install @contextgraph/agent:

npm install -g @contextgraph/agent

Or use with npx:

npx @contextgraph/agent cg <command>

Authentication

The cg CLI uses the same authentication as contextgraph-agent. Run contextgraph-agent auth first:

npx @contextgraph/agent auth

Global Options

• --org <org-id> - Organization ID (use "personal" for Personal Account)

Commands

Read Operations

cg fetch <action-id> - Fetch action details

cg fetch 203cf7c9-d21d-4a4a-9dfc-7e82540c351a --detail-level medium
cg fetch 203cf7c9-d21d-4a4a-9dfc-7e82540c351a --org personal

Options:

• --detail-level <level> - Detail level: small, focus (default), medium, large

cg search <query> - Search for actions

cg search "authentication bug" --mode keyword --limit 5
cg search "login flow" --include-completed --parent-id parent-action-id

Options:

• --mode <mode> - Search mode: vector, keyword, hybrid (default)
• --limit <n> - Maximum results (default: 10)
• --include-completed - Include completed actions
• --parent-id <id> - Search within a specific subtree
• --threshold <n> - Similarity threshold 0-1 (default: 0.3)

cg tree [root-id] - Fetch hierarchical tree view

cg tree --depth 5
cg tree root-action-id --include-completed

Options:

• --depth <n> - Maximum depth (default: 3)
• --include-completed - Include completed actions

cg list-notes <action-id> - Retrieve all notes for an action

cg list-notes 203cf7c9-d21d-4a4a-9dfc-7e82540c351a

Write Operations

cg create - Create a new action

cg create --title "Fix auth bug" --vision "Auth works correctly" --parent-id parent-id
cg create --stdin < action-data.json

Options:

• --title <text> - Action title (required)
• --vision <text> - Action vision (required)
• --parent-id <id> - Parent action ID (required)
• --depends-on <ids> - Comma-separated dependency IDs
• --branch <branch> - Git branch
• --repo <url> - Repository URL
• --freeform <text> - Freeform input text
• --stdin - Read full JSON payload from stdin

cg update <action-id> - Update an existing action

cg update action-id --title "New title" --prepared
cg update action-id --stdin < updates.json

Options:

• --title <text> - Action title
• --vision <text> - Action vision
• --prepared - Mark as prepared
• --agent-ready - Mark as ready for agent execution
• --branch <branch> - Git branch
• --depends-on <ids> - Comma-separated dependency IDs
• --brief <text> - Brief/institutional memory
• --stdin - Read full JSON payload from stdin

cg complete <action-id> - Mark an action as completed

cg complete action-id --visibility public
cg complete action-id --stdin < completion-context.json

Options:

• --visibility <level> - Changelog visibility: private, team, public (required)
• --stdin - Read full completion context from stdin (recommended)

cg append-note <action-id> - Append a note to an action

cg append-note action-id --content "Implementation note"
cg append-note action-id --content "User note" --author-type user --author-name "John"
echo '{"content": "Note from stdin"}' | cg append-note action-id

Options:

• --content <text> - Note content (required if not using stdin)
• --author-type <type> - Author type: user, agent (default), system
• --author-name <name> - Author name

cg uncomplete <action-id> - Mark a completed action as incomplete

cg uncomplete action-id

cg move <action-id> - Move an action to a different parent

cg move action-id --new-parent-id new-parent-id
cg move action-id  # Makes action independent (no parent)

Options:

• --new-parent-id <id> - New parent action ID (omit to make independent)

cg delete <action-id> - Delete an action

cg delete action-id --child-handling reparent --new-parent-id parent-id
cg delete action-id --child-handling delete_recursive

Options:

• --child-handling <mode> - How to handle children: reparent (default), delete_recursive
• --new-parent-id <id> - New parent for children when reparenting (required for reparent mode)

cg report-completed-work - Report work that was already completed

cg report-completed-work --title "Fixed bug" --parent-id parent-id --visibility team
cg report-completed-work --stdin < completed-work.json

Options:

• --title <text> - Action title (required)
• --parent-id <id> - Parent action ID (required)
• --visibility <level> - Changelog visibility (required)
• --stdin - Read full payload from stdin (recommended)

JSON Input/Output

All commands output JSON to stdout. Errors are output as JSON to stderr.

Using stdin for complex data:

Many commands support --stdin to read JSON from stdin. This is especially useful for complex payloads like completion context:

# Create with full payload
echo '{
  "title": "New Action",
  "vision": "Action completed",
  "parent_id": "parent-id",
  "depends_on_ids": ["dep-1", "dep-2"]
}' | cg create --stdin

# Complete with full context
cat completion.json | cg complete action-id --stdin

CLI options override stdin: When both stdin and CLI options are provided, CLI options take precedence:

# Title from CLI overrides stdin
echo '{"title": "From stdin"}' | cg create --stdin --title "Overridden" --vision "Vision" --parent-id "parent"

Filtering output with jq:

# Get just action titles
cg search "bug" | jq -r '.results[].title'

# Get action IDs
cg tree | jq -r '.. | .id? // empty'

# Pretty print
cg fetch action-id | jq .

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Development mode
pnpm dev

License

MIT