Arqitect - LLM-Orchestrated Planning CLI

Arqitect is a sophisticated Node.js CLI tool that intelligently reads codebases, filters relevant files using smart model selection, and generates structured implementation plans. It implements a model-tiered developer assistant pattern that separates filtering, thinking, and doing across different LLMs for improved cost, reliability, and transparency.

Vision

Arqitect introduces an efficient, three-stage LLM pipeline:

1. Smart Model Selection → GPT-5-mini (≤400k tokens) or Gemini 2.5 Flash (>400k tokens) filters relevant code
2. DeepSeek-Reasoner → Advanced reasoning to generate detailed implementation plans
3. Claude Sonnet (manually invoked) → Reads and executes the plan

This approach optimizes cost and performance by using the right model for each task.

Installation

As a Global CLI Tool

npm install -g arqitect
# Or for development:
git clone <repository>
cd arqitect
npm install
npm link

As a Module Dependency

npm install arqitect

Setup

Add your API keys to Replit Secrets or environment variables:

Required:

• GEMINI_API_KEY - Get from Google AI Studio
• DEEPSEEK_API_KEY - Get from DeepSeek API
• OPENAI_API_KEY - Get from OpenAI

See Model Configuration Guide for advanced configuration options.

Usage

Arqitect supports three powerful input methods:

1. Quoted Prompts (Direct Goals)

arqitect "add authentication and RBAC"
arqitect "implement a real-time chat feature"
arqitect "add admin dashboard with role-based access"

2. File Input (Prompts from Files)

arqitect AGENTS.md        # Uses file contents (file must exist)
arqitect requirements.txt # Any readable text file
arqitect PLAN.md         # Even existing plans

3. Multiple Words (Automatic Literal Prompts)

arqitect add user authentication  # Treats as literal prompt
arqitect implement caching system # No quotes needed for multiple words

4. Custom Output Names (Avoid Overwriting)

arqitect "add user auth" --name AUTH     # Creates AUTH.md
arqitect AGENTS.md --name FEATURE        # Creates FEATURE.md
arqitect "implement API" --name DEBUG    # Creates DEBUG.md

Smart Logic:

• Quoted text → Always treated as literal prompt
• Single unquoted word → Treated as file (must exist or error)
• Multiple words → Automatically treated as literal prompt

Default output: Creates PLAN.md when no --name flag is used.

Module Usage (Programmatic)

Arqitect can also be imported and used as a module in your Node.js applications:

ES Modules (Recommended)

import { createArqitectPlan } from 'arqitect';

// Generate a plan programmatically
const plan = await createArqitectPlan('add user authentication');
console.log('Plan generated:', plan);

// Custom filename and directory
const customPlan = await createArqitectPlan(
  'implement caching strategy',
  'CACHING.md', 
  '/path/to/project'
);

CommonJS Projects

// Use dynamic import for CommonJS compatibility
async function useArqitect() {
  const { createArqitectPlan } = await import('arqitect');
  const plan = await createArqitectPlan('add user authentication');
  return plan;
}

// Or create a reusable wrapper
function createArqitectWrapper() {
  return {
    async createPlan(goal, filename) {
      const { createArqitectPlan } = await import('arqitect');
      return createArqitectPlan(goal, filename);
    }
  };
}

Advanced Usage (Pipeline Control)

import { walkFileTree, contextFilter, planner, writePlan } from 'arqitect';

// Full control over each step
const fileMap = await walkFileTree(process.cwd());
const relevantCode = await contextFilter(fileMap, 'add logging');
const plan = await planner(relevantCode, 'add logging');
await writePlan(plan, 'LOGGING.md');

Workflow Integration

import { createArqitectPlan } from 'arqitect';

// Batch processing multiple goals
const goals = ['add auth', 'implement API', 'add tests'];
for (const goal of goals) {
  const filename = `${goal.replace(/\s+/g, '_')}.md`;
  await createArqitectPlan(goal, filename);
}

How It Works

1. 🔍 Scan - Uses repomix to intelligently walk your codebase with gitignore integration
2. ⚙️ Filter - Smart model selection (GPT-5-mini/Gemini) extracts relevant code based on size
3. 📋 Plan - DeepSeek-Reasoner generates structured implementation plans
4. 💾 Output - Writes formatted markdown file (PLAN.md or custom name)

Smart Model Selection

Arqitect automatically chooses the optimal model for your codebase:

• ≤400k tokens: GPT-5-mini (faster, cost-effective)
• >400k tokens: Gemini 2.5 Flash (extended context)
• Planning: DeepSeek-Reasoner (advanced reasoning)

Output Format

Generated plans follow a structured format with:

• 🎯 Clear goal statement
• 🔨 Required changes checklist
• 📂 File-by-file implementation plans
• 🏷️ Responsibility tags (@backend, @frontend, @db, @auth)
• 📝 Implementation notes and assumptions
• ✅ Verification steps

Advanced Features

Multiple Planning Iterations

Use --name to create multiple plans without overwriting:

arqitect "add auth" --name AUTH     # AUTH.md
arqitect "add API" --name API       # API.md  
arqitect "refactor" --name REFACTOR # REFACTOR.md

File-Based Prompts

Store complex prompts in files for reusability:

echo "Implement OAuth2 with GitHub integration" > oauth.md
arqitect oauth.md --name OAUTH

Help and Version

arqitect --help     # Show detailed usage
arqitect --version  # Show version info

Architecture

Core Components

• CLI Entry (bin/cli.js) - Main command-line interface
• File Walking (lib/walkFileTree.js) - Repomix-based codebase scanning
• Context Filtering (lib/contextFilter.js) - Smart model selection and filtering
• Planning (lib/planner.js) - DeepSeek-powered plan generation
• Output Writing (lib/writePlan.js) - Formatted markdown output

Dependencies

• repomix - Professional codebase scanning
• @langchain/openai - GPT model integration
• @langchain/google-vertexai - Gemini model integration
• qerrors - Enhanced error handling and logging
• qtests - Professional testing framework

Testing

Run the comprehensive test suite:

npm test
# Or manually:
node test-runner.js

Tests cover:

• ✅ Module imports and exports
• ✅ Core functionality (file walking, filtering, planning)
• ✅ String formatting utilities
• ✅ Error handling and edge cases

Development

Project Structure

arqitect/
├── bin/cli.js              # CLI entry point
├── lib/                    # Core library
│   ├── walkFileTree.js     # Codebase scanning
│   ├── contextFilter.js    # Smart filtering
│   ├── planner.js          # Plan generation
│   ├── writePlan.js        # Output writing
│   └── *.test.js          # Co-located tests
├── config/                 # Configuration
├── docs/                   # Documentation
└── test-runner.js         # Test orchestration

Key Features

• Dual Interface - CLI and programmatic module usage
• Universal Compatibility - Works with ES modules and CommonJS
• ES Modules - Modern JavaScript module system
• Single Responsibility - One function per file architecture
• Professional Error Handling - qerrors integration
• Comprehensive Testing - qtests framework
• Smart Model Selection - Automatic optimization
• File Input Support - Prompts from files
• Custom Output Names - Multiple planning iterations
• Workflow Integration - Easy integration into existing tools

Troubleshooting

Common Issues

API Keys Not Working

• Verify all three keys are set: GEMINI_API_KEY, DEEPSEEK_API_KEY, OPENAI_API_KEY
• Check key permissions and quotas

Large Codebase Timeouts

• Arqitect automatically switches to Gemini for large codebases
• Consider filtering specific directories in .gitignore

Command Not Found

• Run npm link to make arqitect globally available
• Or use node bin/cli.js directly

DeepSeek Timeouts

• Default planning model is optimized for reliability
• Customize via environment variables (see configuration guide)

Configuration

For advanced model configuration, custom endpoints, and optimization settings, see:

• Model Configuration Guide
• Environment Variables Reference

API Reference

Core Functions

createArqitectPlan(goal, filename?, workingDir?)

High-level function that orchestrates the complete pipeline.

• goal: String describing the architectural goal
• filename: Optional custom output filename (default: 'PLAN.md')
• workingDir: Optional directory to scan (default: process.cwd())
• Returns: Promise<string> - The generated plan content

walkFileTree(directory)

Scans codebase using repomix with gitignore integration.

• Returns: Promise<Object> - File map with paths and contents

contextFilter(fileMap, goal)

Intelligently filters relevant code using smart model selection.

• Returns: Promise<string> - Filtered, relevant code context

planner(relevantCode, goal)

Generates structured implementation plan using DeepSeek-Reasoner.

• Returns: Promise<string> - Formatted markdown plan

writePlan(planContent, filename?)

Writes plan content to specified file.

• Returns: Promise<void>

Examples

See example-module-usage.js for comprehensive usage examples including:

• Simple one-line plan generation
• Advanced pipeline control
• Workflow integration patterns

Contributing

1. Follow the single responsibility principle (one function per file)
2. Add comprehensive JSDoc documentation
3. Include co-located tests using qtests framework
4. Use qerrors for error handling and logging
5. Update documentation for any new features
6. Test both CLI and module interfaces

License

Apache 2.0 License - See LICENSE file for details.

arqitect/
├── bin/
│   └── cli.js              # Entry point CLI
├── lib/
│   ├── walkFileTree.js     # Recursively reads code files
│   ├── contextFilter.js     # Uses Gemini to extract relevant code
│   ├── deepseekPlanner.js  # Uses DeepSeek to generate PLAN.md
│   └── writePlan.js        # Writes PLAN.md file
├── config/
│   └── settings.js         # Loads environment variables
└── README.md

Testing

npm test

This runs basic module import and file tree walking tests.