@conturalis/conpacts-cli

Conpacts is a State-of-the-Art (SOTA) local AI pair-programmer and codebase RAG engine.

Designed for enterprise teams and complex monorepos, Conpacts natively understands your local directory structure, builds local vector maps using AST (Abstract Syntax Trees), and surgically executes codebase modifications directly on your disk.

It ships with a fully extensible Inversion of Control (IoC) architecture, allowing your team to bring your own AI models, custom security rules, and bespoke engineering personas.

Key Features

• WASM-Powered AST Indexing: Utilizes web-tree-sitter to parse your JavaScript, TypeScript, Python, Go, and PHP files into Abstract Syntax Trees out-of-the-box. It chases local dependencies without requiring messy native C++ node-gyp builds.
• Dual Interface Modes:
  • conpacts cli: A hyper-fast terminal REPL for quick autonomous codebase operations.
  • conpacts studio: A beautiful, local web interface powered by Server-Sent Events (SSE) with a dual-track markdown and thought-block rendering engine.
• Enterprise AI Routing: Seamlessly switches between public Generative AI (via API keys) and native Enterprise Google Cloud (via Application Default Credentials) based strictly on your local environment variables.
• Surgical Disk Operations: The AI doesn't just give you code to copy-paste. Using specific Pacts (!!build, !!code), it utilizes native tool calls to regex, patch, or rewrite target files directly in your IDE.
• 100% Agnostic IoC Configuration: Drop in your own Gemini, OpenAI, or custom enterprise AI adapters via the local workspace configuration.
• Smart Prompt Overrides: Completely overwrite the baseline AI personas (Studio, CLI, and RAG Librarian) by simply dropping .md files into a local folder.

Core Rule: The Workspace Root

Conpacts utilizes an Inversion of Control (IoC) architecture. The CLI is a "dumb" agnostic engine; it gets its brains entirely from the directory where you type the command (process.cwd()).

You must always execute conpacts commands from your project's root folder (where your .env and .conpacts/ folder reside). If you run it from a subfolder, it will not find your configurations.

Environment Auto-Discovery

Conpacts utilizes a native, ES-Module-safe bootloader to inject your environment variables before any core modules load, ensuring zero dependency on third-party packages like dotenv.

• Flag Support: Target specific environments instantly by passing a flag (e.g., conpacts cli --env=prod natively resolves to .env.prod).
• Interactive Fallback: If no flag is passed and multiple .env files are found in your workspace root, the bootloader pauses and prompts you to select one interactively.
• Non-Destructive Injection: The system manually parses your .env file and assigns values to process.env only if they do not already exist, strictly protecting your OS-level variables.

Installation

Conpacts requires a two-part installation: globally (for the command-line executables) and locally (for your project's workspace configuration to resolve the core AI adapters).

# 1. Install the executable globally
npm install -g @conturalis/conpacts-cli

# 2. Enter your project workspace
cd ~/my-awesome-project

# 3. Scaffold the private .conpacts/ IoC directory & environment variables
conpacts init

# 4. Install locally so your generated config can resolve the internal packages
npm install @conturalis/conpacts-cli

⚠️ Windows Users: You must use PowerShell, Git Bash, or WSL to run the CLI REPL. The legacy Windows Command Prompt (cmd.exe) contains a known bug with nested Node.js stdin streams that will freeze your keyboard input.

Updating the Package

Because you rely on both a global binary and a local workspace dependency, you must explicitly update both while clearing the NPM cache to prevent stale registry pulls.

# 1. Clear the cache to prevent stale registry pulls
npm cache clean --force

# 2. Update the global executable
npm install -g @conturalis/conpacts-cli@latest

# 3. Enter your project workspace
cd /path/to/your/project/root

# 4. Update the local workspace dependency
npm install @conturalis/conpacts-cli@latest

Quick Start

1. Configure Your AI Routing (Smart Adapters)

Conpacts ships with a dual-adapter configuration template. It automatically detects which AI route to take based entirely on your .env file.

Option A: The External Route (Public Gemini API) Ideal for solo developers or testing. Requires a standard Google AI Studio key.

1. Open your .env file.
2. Ensure you have:

GEMINI_API_KEY="AIzaSyYourKeyHere..."
CONPACTS_MODEL="gemini-1.5-pro-latest"

(If GEMINI_API_KEY is present, Conpacts will automatically route via the Public API).

Option B: The Enterprise Route (Native GCP Vertex AI) Ideal for enterprise teams mapping billing and telemetry directly to Google Cloud.

1. Create a Service Account in GCP, grant it the necessary roles, and download the JSON key to your project root (e.g., conpacts-key.json).
2. CRITICAL: Add conpacts-key.json to your .gitignore.
3. Open your .env file and delete the GEMINI_API_KEY line entirely.
4. Ensure you have:

GOOGLE_CLOUD_PROJECT="your-company-project-id"
LOCATION=""
CONPACTS_MODEL=""
GOOGLE_APPLICATION_CREDENTIALS="./conpacts-key.json"

2. Boot the Engine & Build the Vector Index

Before the AI can navigate your repository, you must map the terrain by chunking and indexing your codebase into AST vectors.

Launch the Terminal REPL Operator from your root folder:

conpacts cli

Once inside the Conpacts interface, ask the AI to trigger the indexer on your target source folders:

Conpacts ❯ !!index --target src/ packages/

(This native execution generates a .conpacts/.conpacts_index.json vector map locally).

3. Launch the Web Studio (Optional)

If you prefer a visual dual-track UI with thought-block rendering after building your index, simply boot the web interface from another terminal:

conpacts studio

The Pact Protocol

Conpacts operates using strict directives called Pacts. You append these to your messages to dictate exactly how the AI should behave and what tools it should invoke.

| Pact | Engine Mode | Description | | :--- | :--- | :--- | | !!chat | Studio/CLI | Conversational sparring. Bypasses disk modifications and tools. | | !!plan | Studio/CLI | Reads workspace architecture and drafts a step-by-step execution plan. | | !!code | Studio/CLI | Instructs the AI to evaluate logic and provide surgical code blocks. | | !!build | Studio/CLI | Scaffolds entirely new files securely to the disk based on an approved plan. | | !!run !script | CLI Only | Allows the CLI agent to natively execute local NPM/Bash scripts. |

Advanced Workspace Configuration

When you ran conpacts init, the framework generated a .conpacts/ folder in your project root. This is your completely private, Git-ignored control center. It contains:

1. conpacts.config.mjs (The Engine Tuning): Open this file to adjust the RAG Semantic Thresholds, increase the Max Anchor Files injected into context, register Polyglot WASM parsers, or define pricing metrics for unmapped open-source models.
2. prompts/ (Custom Personas): Drop .md files here to completely override the default AI brains with your company's proprietary coding guidelines and security matrices. Read the README.md inside this folder for full instructions on how to port baseline capabilities to your custom agents.
3. tools/ (Private Infrastructure): Drop your custom Javascript files here, export a declaration and execute function, and register them in your conpacts.config.mjs to grant the AI secure access to your proprietary databases and internal APIs.

Polyglot AST Parsing (Bring Your Own WASM)

To enable AST-level precision for other languages (e.g., Rust, Java, C++), you must provide the compiled .wasm grammars to your .conpacts/ folder and map them in the indexer config. Because official Tree-sitter NPM packages compile to C++ native bindings by default, the easiest way to acquire the binaries is to build them natively:

# 1. Install the Tree-sitter CLI globally
npm install -g tree-sitter-cli

# 2. Clone the official grammar repository (e.g., Rust)
git clone https://github.com/tree-sitter/tree-sitter-rust.git
cd tree-sitter-rust

# 3. Compile the grammar to WebAssembly (Requires Docker or Emscripten installed)
tree-sitter build --wasm

# 4. Move the resulting binary to your workspace
mv tree-sitter-rust.wasm /path/to/your/project/.conpacts/

Security & Telemetry

• Zero Telemetry: Conpacts operates entirely on your local machine. No tracking, no external logging.
• Blast Radius Control: Tool executions are strictly bound to the process.cwd() (the folder where you booted the CLI). It cannot reach out and modify files across your OS.
• Bring Your Own Keys: API keys and credentials live securely in your local .env or system configurations. They are never transmitted back to Conturalis.

Built for the future of local AI infrastructure.