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

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Development mode
pnpm dev

License

MIT