QuantumAgent

🧠 Parallel Reasoner Subagent CLI Tool

A specialized CLI tool that enables LLM orchestrators (like Claude or Replit Agent) to spawn focused reasoner subagents for parallel analysis and reasoning using Gemini 2.5 Flash via LangChain and Google Vertex AI. Reasoner subagents analyze context, identify problems, and return structured suggestions and proposed patches without modifying code directly.

🎯 Purpose

• Reasoner Delegation: Enable main agents to offload complex reasoning tasks to specialized subagents
• Parallel Analysis: Reduce analysis latency through parallel reasoner deployment while main agent continues other work
• Structured Suggestions: Returns structured recommendations, patches, and proposed changes in stout format
• No Direct Modification: Reasoner subagents analyze and suggest only - they never modify repository files
• Context-Driven Reasoning: Deep analysis based on focused, well-prepared context files

🚀 Quick Start

Installation

npm install quantumagent
# or
npm install -g quantumagent

Setup

1. Copy the environment template:

cp .env.example .env

2. Add your Google Vertex AI credentials to .env:

# Option 1: API Key (simpler)
GOOGLE_API_KEY=your_vertex_ai_api_key_here
LLM_MODEL=gemini-2.5-flash

# Option 2: Service Account (recommended)
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

CLI Usage (AI-First Design)

QuantumAgent is designed for AI/LLM usage with explicit paths for maximum reliability.

Use explicit node_modules paths instead of short commands to avoid resolution errors:

# Basic reasoner analysis with input file  
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: analyze authentication security (DO NOT MODIFY CODE)" --input ./context.txt

# Get help information
node node_modules/quantumagent/.bin/cli.js --help

# Using stdin for context
cat context.txt | node node_modules/quantumagent/.bin/cli.js --task "Reasoner: suggest database optimizations (DO NOT MODIFY CODE)" --stdin

# Direct context as arguments
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: audit API endpoints for security issues (DO NOT MODIFY CODE)" "JWT authentication with user sessions"

Why Full Paths: This eliminates dependency on shell PATH, symlinks, npx resolution, or package.json scripts - ensuring consistent execution for AI agents across different environments.

Default Output: QuantumAgent uses stout format by default - a structured output perfect for reasoner analysis with sections for STATUS, SUMMARY, proposed CODE patches, and NEXT_STEPS.

CLI Parameters

• --task: (Required) Description of the task to execute
• --input: (Optional) Path to file containing context
• --stdin: (Optional) Read context from stdin
• --help: Display help message and usage examples

Output Format: Always uses structured stout format with STATUS, FILES, CODE, SUMMARY, and NEXT_STEPS sections.

Programmatic Usage

import { runQuantumAgent } from 'quantumagent';

const result = await runQuantumAgent({
  context: 'I need to build a REST API with user authentication...',
  task: 'Reasoner: analyze authentication requirements and propose secure login implementation (DO NOT MODIFY CODE)'
});

console.log(result);

📋 Stout Format

All responses follow this structured format:

=== SUBAGENT RESULT ===
STATUS: SUCCESS
TASK: Create login endpoint
FILES_MODIFIED: 1
FILES_CREATED: 2
=== FILES ===
CREATED: routes/auth.js
CREATED: middleware/auth.js
MODIFIED: app.js
=== CODE ===
--- routes/auth.js ---
[full file content]
--- middleware/auth.js ---
[full file content]
--- app.js (changes) ---
[only the changes/additions]
=== SUMMARY ===
- Created authentication routes with login/logout endpoints
- Added JWT middleware for token validation
=== NEXT_STEPS ===
- Test the endpoints with Postman
- Add password hashing with bcrypt
=== END ===

🏗️ Architecture

• CLI Entry Point: src/cli.js - Handles argument parsing and I/O
• Core Runner: src/runner.js - LangChain + Gemini execution
• Prompt Templates: src/boilerplates.js - System prompts for different formats
• Validator: src/validator.js - Format validation and fallback generation

💡 Examples

Security Analysis Reasoning

# Context: Express app authentication analysis
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: analyze JWT authentication security and propose hardening measures (DO NOT MODIFY CODE)" \
--input security-analysis-context.txt

API Design Review

# Context file: api-requirements.txt  
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: evaluate RESTful API design and suggest improvements (DO NOT MODIFY CODE)" --input api-requirements.txt

Performance Bottleneck Analysis

# Direct performance troubleshooting
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: identify memory leak causes and suggest fixes (DO NOT MODIFY CODE)" \
--input performance-context.txt

Legacy Code Assessment

# Using stdin for large codebase analysis
cat legacy-callbacks.js | node node_modules/quantumagent/.bin/cli.js --task "Reasoner: assess modernization opportunities for callback-based code (DO NOT MODIFY CODE)" --stdin

Database Optimization Review

node node_modules/quantumagent/.bin/cli.js --task "Reasoner: analyze database architecture and suggest optimization strategies (DO NOT MODIFY CODE)" \
--input database-context.txt

🔗 Integration

QuantumAgent is designed to be called by AI orchestrators:

• Replit Agent: Execute multiple subagents in parallel from PLAN.md
• Claude: Parse stout responses and apply file changes
• Custom Tools: Integrate via CLI or programmatic API

Parallel Reasoner Orchestration

# Multiple parallel reasoner subagents for comprehensive analysis
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: analyze user authentication flow (DO NOT MODIFY CODE)" --input auth-context.txt &
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: review API security patterns (DO NOT MODIFY CODE)" --input api-security-context.txt &
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: assess database performance (DO NOT MODIFY CODE)" --input db-performance-context.txt &
wait

🚨 Error Handling

QuantumAgent includes enterprise-grade error handling with typed errors and enhanced logging:

• Authentication Errors: Clear messages for API key issues
• Validation Errors: Helpful guidance for input problems
• Network Errors: Automatic retries with exponential backoff
• Rate Limits: Graceful handling with user-friendly messages

Common Issues

1. Missing API Key: Set GOOGLE_API_KEY in your environment or .env file
2. No Context Provided: Include context via --input file, --stdin, or direct argument
3. API Quotas: Check Google AI Studio usage limits

Fallback Behavior

If any error occurs, QuantumAgent returns a structured FAILURE stout block with diagnostic information, ensuring consistent output format even during failures.

📋 Best Practices

Context Guidelines

• Be Specific: Include relevant code snippets, file structures, requirements
• Stay Focused: One clear task per call for best results
• Provide Context: Include necessary background information

Task Descriptions

• Clear Objectives: "Create auth endpoint" vs "Make it work"
• Specific Requirements: Include technologies, patterns, constraints
• Scope Boundaries: What should and shouldn't be included

Parallel Execution

• Independent Tasks: Ensure tasks don't have dependencies on each other
• Separate Contexts: Each subagent should have complete context for its task
• Result Integration: Plan how to merge results from parallel executions

Integration with Development Workflows

Pre-commit Analysis (AI-First Commands)

# Use reasoners for pre-commit code analysis with full paths
git diff --name-only --cached | while read file; do
  if [[ $file == *.js || $file == *.ts ]]; then
    node node_modules/quantumagent/.bin/cli.js --task "Reasoner: pre-commit analysis - review changes for quality, security, and performance (DO NOT MODIFY CODE)" --input "$file" > "analysis-${file//\//-}.txt" &
  fi
done
wait

CI/CD Pipeline Integration

# Automated code review in CI pipeline
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: CI code review - analyze changes for quality regression and security issues (DO NOT MODIFY CODE)" --input ./changed-files-context.txt > ci-review-results.txt

# Multi-aspect parallel analysis for CI
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: security vulnerability scan (DO NOT MODIFY CODE)" --input ./security-context.txt &
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: performance regression analysis (DO NOT MODIFY CODE)" --input ./performance-context.txt &
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: code quality assessment (DO NOT MODIFY CODE)" --input ./quality-context.txt &
wait

Documentation Analysis

# Generate documentation insights using reasoner analysis
node node_modules/quantumagent/.bin/cli.js --task "Reasoner: analyze codebase and suggest comprehensive API documentation improvements (DO NOT MODIFY CODE)" --input ./api-context.txt > api-documentation-analysis.txt

AI-First Design Note: All commands use explicit node node_modules/quantumagent/.bin/cli.js paths to eliminate dependency on shell PATH, symlinks, npx resolution, or package.json scripts - ensuring consistent execution for AI agents across different environments.

Remember: Reasoner subagents are analysis tools that provide structured recommendations - main agents implement the suggested changes.

Context Engineering

The rules folders for Cline Code & Kilocode are symlinked to the folder for Roo Code rules. 00-general.md in Roo Code rules is symlinked to AGENTS.md

ln -s "$(pwd)/.roo/rules" "$(pwd)/.kilocode/rules"

ln -s "$(pwd)/.roo/rules" "$(pwd)/.clinerules/"

ln -s "$(pwd)/AGENTS.md" "$(pwd)/.roo/rules/00-general.md"

Replacement Installation of other apps (only to over-write this project entirely, in order to get them Replit Agent)

git remote set-url origin https://github.com/yourusername/yourrepo.git

git remote -v

git fetch

git reset origin/main --hard