Autonomous agent for contextgraph action execution
npm install @contextgraph/agentAutonomous agent for contextgraph action execution.
No installation required! Use npx to run commands directly:
``bash`
npx @contextgraph/agent
Or install globally for convenience:
`bash`
npm install -g @contextgraph/agent
- Node.js 18 or higher
- Active contextgraph.dev account
1. Authenticate with contextgraph.dev:
`bash`
npx @contextgraph/agent auth
2. Run the agent:
`bash`
npx @contextgraph/agent run
For automated environments, use an API token:
`bash`
export CONTEXTGRAPH_API_TOKEN="your-api-token"
npx @contextgraph/agent run
Get your API token from https://contextgraph.dev/settings/tokens
`bash`
npx @contextgraph/agent auth
Opens your browser to complete authentication. Credentials are securely stored in ~/.contextgraph/.
`bash`
npx @contextgraph/agent whoami
Shows your user ID and token expiration.
`bash`
npx @contextgraph/agent run
The agent will:
1. Fetch the action tree
2. Find the next unprepared/incomplete leaf action
3. Prepare it (if needed) - assess if it should be broken down
4. Execute it - implement the work using Claude
5. Repeat until all actions are complete
`bash`
npx @contextgraph/agent prepare
Spawns Claude to assess whether the action should be broken down into child actions or is ready to execute.
`bash`
npx @contextgraph/agent execute
Spawns Claude to implement the action and mark it complete.
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
If authentication fails or tokens expire:
`bash`
npx @contextgraph/agent auth
This will open a new browser session to re-authenticate.
Tokens expire after a period of time. Re-authenticate with:
`bash`
npx @contextgraph/agent whoami # Check expiration
npx @contextgraph/agent auth # Re-authenticate if expired
Ensure you have internet connectivity and can reach:
- https://www.contextgraph.dev (API endpoint)
- https://contextgraph.dev (authentication)
- contextgraph.dev - Main platform
- GitHub Repository - Source code and issues
- Issue Tracker - Report bugs or request features
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:
`bash`
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.
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:
`bash`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
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:
`bash`
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:
1. Visit the Anthropic Console API Keys page
2. Click "Create Key" to generate a new API key
3. Give it a descriptive name (e.g., "Production Worker" or "CI/CD Pipeline")
4. Copy the key immediately - it won't be shown again
5. 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).
`bashInstall dependencies
pnpm install
MIT