@agentics.org/sparc2
Advanced tools
SPARC 2.0 - Autonomous Vector Coding Agent + MCP. SPARC 2.0, vectorized AI code analysis, is an intelligent coding agent framework built to automate and streamline software development. It combines secure execution environments, and version control into a
SPARC 2.0: agentic code analysis and generation. It's an intelligent coding agent framework built to automate and streamline software development. It combines secure execution environments, vector similarity (Code and Unified Diffs), version control, secure sandbox/code interpreter, OpenAi agents API and Model Context Protocol (MCP) capabilities into a unified system where specialized agents collaborate to understand, modify, and manage code.
These agents analyze patterns, suggest improvements, implement changes, and validate solutions, all while maintaining a detailed history that allows for easy rollbacks when needed.
npm install -g @agentics.org/sparc2
By bridging the gap between human developers and AI assistants, SPARC 2.0 enhances productivity across the entire development lifecycle, from initial code review to final deployment.
A defining feature of SPARC is its ability to track code changes over time, functioning like a perfect memory of your code's evolution. It uses a unified diff system to capture precisely what changed between versions rather than storing entire files, dramatically reducing storage needs and speeding up operations. By default, the system tracks changes at the file level for optimal performance, yet it can zoom in to function-level tracking when more granular detail is required. This efficient diff tracking ensures smooth performance whether you are working on a small project or a massive enterprise codebase.
Essentially, SPARC acts as an advanced version control enhancer that integrates with Git and GitHub while leveraging artificial intelligence to manage updates automatically. Its understanding of temporal relationships between code modifications allows it to orchestrate complex workflows that support simultaneous contributions from both human developers and AI agents. SPARC adapts its processing pace to match developers' speed, ensuring seamless, conflict-free collaboration.
At the heart of SPARC lies its vector store, a specialized database that transforms code and text into abstract patterns. Instead of merely memorizing exact words, it captures the underlying meaning of the code, similar to understanding cooking techniques rather than just listing ingredients. This approach enables the system to locate similar code snippets despite differences in variable names or styles, creating a smart library of your development history.
Another key element is its integrated code interpreter built using E2B—a language-agnostic execution environment that builds, runs, and modifies code without relying on a traditional IDE. It creates secure, isolated sandboxes for execution across languages such as Python, JavaScript, TypeScript, Go, Rust, and more.
SPARC 2.0 employs a ReACT (Reason + Act) strategy to semantically understand code. It first reasons about what the code means and then takes appropriate actions. This combination of efficient diff tracking and intelligent reasoning enables rapid processing of large codebases without sacrificing deep comprehension of the code's purpose and structure.
At its core, SPARC 2.0 uses advanced diff tracking to compare previous and updated versions of code:
SPARC 2.0 supports multiple processing modes:
SPARC 2.0 is ideal for:
# Install globally
npm install -g @agentics.org/sparc2
# Or install locally in your project
npm install --save-dev @agentics.org/sparc2
# Clone the repository
git clone https://github.com/agentics-org/sparc2.git
cd sparc2
# Install dependencies
deno cache --reload src/cli/cli.ts
A comprehensive command-line interface for the SPARC2 project that integrates the E2B code interpreter and agent framework implementations.
If you installed via npm:
# The CLI is available as the 'sparc2' command
sparc2 --help
# You can also use the 'sparc' command for direct execution
sparc --help
If you cloned the repository:
# Create an alias for easier use
alias sparc2="deno run --allow-read --allow-write --allow-env --allow-net --allow-run /path/to/sparc2/src/cli/cli.ts"
# Or use the provided script
./sparc --help
SPARC2 CLI provides the following commands:
SPARC2 uses TOML configuration files:
config/sparc2-config.toml: General configurationconfig/agent-config.toml: Agent-specific configurationYou can also set the configuration path using the environment variable:
export SPARC2_CONFIG_PATH=/path/to/your/config.toml
Create a .env file in your project root (you can copy from .env.example) or set these environment variables:
# Required
- `OPENAI_API_KEY`: Your OpenAI API key
- `E2B_API_KEY`: Your E2B API key
# Optional
- `OPENROUTER_API_KEY`: Your OpenRouter API key (optional)
- `SPARC2_CONFIG_PATH`: Custom path to your config file
- `NPM_TOKEN`: Your NPM token (only needed when publishing to npm)
- `MCP_SECRET_KEY`: Secret key for MCP server authentication
SPARC2 includes a Model Context Protocol (MCP) server that allows AI agents to interact with your codebase. The MCP server provides a standardized interface for tools and resources discovery, enabling seamless integration with AI assistants.
SPARC2 provides two different ways to use the Model Context Protocol (MCP):
The api command starts an HTTP server that implements the MCP protocol over HTTP:
# Using the sparc command
./sparc api --port 3001
# Or with npm installation
sparc2 api --port 3001
Options:
--port, -p: Port to run the API server on (default: 3001)--model: Model to use for the agent--mode: Execution mode (automatic, semi, manual, custom, interactive)--diff-mode: Diff mode (file, function)--processing: Processing mode (sequential, parallel, concurrent, swarm)--config, -c: Path to the agent configuration fileThis is useful for integrations that communicate with SPARC2 over HTTP.
The mcp command starts a server that implements the MCP protocol over standard input/output (stdio):
# Using the sparc command
./sparc mcp
# Or with npm installation
sparc2 mcp
Options:
--model: Model to use for the agent--mode: Execution mode (automatic, semi, manual, custom, interactive)--diff-mode: Diff mode (file, function)--processing: Processing mode (sequential, parallel, concurrent, swarm)--config, -c: Path to the agent configuration fileThis is useful for integrations with tools like VS Code extensions that communicate with SPARC2 over stdio.
To use SPARC2 with VS Code extensions that support the Model Context Protocol (MCP), you'll need to configure the extension's settings. Here's an example configuration for the Claude extension:
{
"mcpServers": {
"sparc2-mcp": {
"command": "node",
"args": [
"/path/to/sparc2/src/mcp/mcpServerWrapper.js"
],
"workingDirectory": "/path/to/sparc2",
"disabled": false,
"autoApprove": [
"analyze_code",
"modify_code",
"search_code",
"create_checkpoint",
"rollback",
"config"
],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"OPENROUTER_API_KEY": "your-openrouter-api-key",
"E2B_API_KEY": "your-e2b-api-key",
"MCP_SECRET_KEY": "your-mcp-secret-key",
"SPARC2_CONFIG_PATH": "/path/to/sparc2/config.toml",
"SPARC2_AGENT_CONFIG_PATH": "/path/to/sparc2/agent-config.toml",
"OPENAI_MODEL": "gpt-4o"
},
"timeout": 300
}
}
}
The MCP server wrapper automatically detects the Deno executable in various common installation locations, making it portable across different systems.
The MCP server exposes the following endpoints:
The SPARC2 MCP server provides the following tools:
Analyzes code files for issues and improvements.
Parameters:
files: Array of file paths to analyze (required)task: Description of the analysis taskReturns: Analysis results with suggestions for improvements
Applies suggested modifications to code files.
Parameters:
files: Array of file paths to modify (required)task: Description of the modification taskReturns: Results of the modifications applied
Executes code in a secure sandbox.
Parameters:
code: Code to execute (required)language: Programming language (python, javascript, typescript) (required)Returns: Execution results including stdout, stderr, and any errors
Searches for similar code changes.
Parameters:
query: Search query (required)limit: Maximum number of results to returnReturns: Array of search results with relevance scores
Creates a version control checkpoint.
Parameters:
name: Checkpoint name (required)Returns: Checkpoint information including commit hash
Rolls back to a previous checkpoint.
Parameters:
commit: Commit hash to roll back to (required)Returns: Result of the rollback operation
Manages configuration.
Parameters:
action: Action to perform (get, set, list) (required)key: Configuration key (required for get/set)value: Configuration value (required for set)Returns: Configuration operation result
The SPARC2 MCP server provides the following resources:
Git repository for version control and checkpointing.
Properties:
path: Path to the git repositorybranch: Current branch nameMethods:
name (Name of the checkpoint)commit (Commit hash to roll back to)Vector database for storing and searching code changes and logs.
Properties:
id: ID of the vector storesize: Number of entries in the vector storeMethods:
query (Search query), limit (Maximum number of results)content (Content to index), metadata (Metadata for the entry)Secure sandbox for executing code.
Properties:
languages: Supported programming languagestimeout: Maximum execution time in secondsMethods:
code (Code to execute), language (Programming language)You can test the MCP server endpoints using curl commands. First, start the MCP server:
./sparc api --port 3001
curl -X GET http://localhost:3001/discover
This will return a JSON object containing all available tools and resources.
curl -X POST http://localhost:3001/execute_code \
-H "Content-Type: application/json" \
-d '{
"code": "console.log(\"Hello, SPARC2!\"); const sum = (a, b) => a + b; console.log(sum(5, 3));",
"language": "javascript"
}'
Response:
{
"result": "Hello, SPARC2!\n8",
"details": {
"logs": {
"stdout": ["Hello, SPARC2!", "8"],
"stderr": []
}
}
}
curl -X POST http://localhost:3001/analyze_code \
-H "Content-Type: application/json" \
-d '{
"files": ["path/to/file.js"],
"task": "Check for performance issues and suggest improvements"
}'
curl -X POST http://localhost:3001/modify_code \
-H "Content-Type: application/json" \
-d '{
"files": ["path/to/file.js"],
"task": "Optimize the rendering function"
}'
curl -X POST http://localhost:3001/search_code \
-H "Content-Type: application/json" \
-d '{
"query": "Fix performance issue in rendering",
"limit": 5
}'
curl -X POST http://localhost:3001/create_checkpoint \
-H "Content-Type: application/json" \
-d '{
"name": "Optimized rendering function"
}'
curl -X POST http://localhost:3001/rollback \
-H "Content-Type: application/json" \
-d '{
"commit": "abc123def456"
}'
List configuration:
curl -X POST http://localhost:3001/config \
-H "Content-Type: application/json" \
-d '{
"action": "list"
}'
Get a specific configuration value:
curl -X POST http://localhost:3001/config \
-H "Content-Type: application/json" \
-d '{
"action": "get",
"key": "DIFF_MODE"
}'
Set a configuration value:
curl -X POST http://localhost:3001/config \
-H "Content-Type: application/json" \
-d '{
"action": "set",
"key": "DIFF_MODE",
"value": "function"
}'
SPARC2 can also be used as a library in your own projects:
import { SPARC2Agent } from '@agentics.org/sparc2';
Analyze code files for issues and improvements:
deno run --allow-read --allow-write --allow-env --allow-net src/cli/cli.ts analyze --files path/to/file.js
Or if installed via npm:
sparc2 analyze --files path/to/file.js
Options:
--files: Comma-separated list of files to analyze (required)--output, -o: Output file for analysis results--model: Model to use for analysis--mode: Execution mode (automatic, semi, manual, custom)--diff-mode: Diff mode (file, function)--processing: Processing mode (parallel, sequential, concurrent, swarm)Apply suggested modifications to code files:
deno run --allow-read --allow-write --allow-env --allow-net src/cli/cli.ts modify --files path/to/file.js --suggestions "Fix the bug in the multiply function"
Or if installed via npm:
sparc2 modify --files path/to/file.js --suggestions "Fix the bug in the multiply function"
Options:
--files: Comma-separated list of files to modify (required)--suggestions, -s: Suggestions file or string (required)--model: Model to use for modifications--mode: Execution mode (automatic, semi, manual, custom)--diff-mode: Diff mode (file, function)--processing: Processing mode (parallel, sequential, concurrent, swarm)Execute code in a sandbox:
deno run --allow-read --allow-write --allow-env --allow-net src/cli/cli.ts execute --file path/to/file.js
Or if installed via npm:
sparc2 execute --file path/to/file.js
Options:
--file: File to execute--code: Code to execute (alternative to --file)--language, -l: Programming language (python, javascript, typescript)--stream: Stream output (boolean)--timeout: Timeout in millisecondsSearch for similar code changes:
deno run --allow-read --allow-write --allow-env --allow-net src/cli/cli.ts search --query "Fix multiplication bug"
Or if installed via npm:
sparc2 search --query "Fix multiplication bug"
Options:
--query: Search query (required)--max-results, -n: Maximum number of results (default: 5)Create a git checkpoint:
deno run --allow-read --allow-write --allow-env --allow-net src/cli/cli.ts checkpoint --message "Fixed multiplication bug"
Or if installed via npm:
sparc2 checkpoint --message "Fixed multiplication bug"
Options:
--message, -m: Checkpoint message (required)Rollback to a previous checkpoint:
deno run --allow-read --allow-write --allow-env --allow-net src/cli/cli.ts rollback --commit abc123
Or if installed via npm:
sparc2 rollback --commit abc123
Options:
--commit: Commit hash or date to rollback to (required)Manage configuration:
deno run --allow-read --allow-write --allow-env --allow-net src/cli/cli.ts config --action list
Or if installed via npm:
sparc2 config --action list
Options:
--action: Configuration action (get, set, list) (required)--key: Configuration key (required for get/set)--value: Configuration value (required for set)sparc2 analyze --files src/app.js
sparc2 modify --files src/app.js,src/utils.js --suggestions suggestions.txt
sparc2 execute --file script.py --language python
sparc2 search --query "Fix performance issue" --max-results 10
sparc2 checkpoint --message "Implemented new feature"
sparc2 rollback --commit "2023-01-01"
sparc2 config --action get --key "models.reasoning"
sparc2 config --action set --key "models.reasoning" --value "gpt-4o"
./sparc api --port 3001
./sparc mcp
sparc2 analyze --files src/app.js --model gpt-4o --processing parallel
sparc2 modify --files src/app.js --suggestions "Optimize the rendering function" --diff-mode function
sparc2 execute --file script.py --language python --stream
#!/bin/bash
# Analyze and fix performance issues
# Analyze the code
sparc2 analyze --files src/app.js --output analysis.json
# Apply fixes
sparc2 modify --files src/app.js --suggestions analysis.json
# Create a checkpoint
sparc2 checkpoint --message "Fixed performance issues"
# Test the changes
sparc2 execute --file src/app.js
Run the CLI tests:
deno test --allow-read --allow-write --allow-env --allow-net --allow-run tests/cli-test.ts
MIT
FAQs
SPARC 2.0 - Autonomous Vector Coding Agent + MCP. SPARC 2.0, vectorized AI code analysis, is an intelligent coding agent framework built to automate and streamline software development. It combines secure execution environments, and version control into a
We found that @agentics.org/sparc2 demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh joins Risky Business Weekly to unpack recent npm phishing attacks, their limited impact, and the risks if attackers get smarter.
Product
Socket’s new Tier 1 Reachability filters out up to 80% of irrelevant CVEs, so security teams can focus on the vulnerabilities that matter.
Research
/Security News
Ongoing npm supply chain attack spreads to DuckDB: multiple packages compromised with the same wallet-drainer malware.