ACE CLI (ace)

A local-first, git-based CLI for managing project knowledge bases with context trees, agent connectors, and pattern detection.

Features

• Local-Only - No authentication, no remote sync, all data in git
• Interactive REPL - TUI with slash commands, tab completion, and live feedback
• Context Tree - Hierarchical knowledge base with domains, topics, and subtopics
• Context Engine - Incremental local indexing with hybrid (lexical + semantic) retrieval
• Agent Connectors - Integrate with AI coding assistants (Claude, Cursor, Copilot, etc.)
• Durable Agent Memory - Local SQLite + JSONL journal memory for Codex, Claude Code, VS Code, and more
• Pattern Detection - Automatically detect project patterns (frameworks, testing, architecture, security)
• Git-Based - Store and version your knowledge base alongside your code
• Cross-platform - Works on macOS, Windows, Linux, and WSL

Installation

npm install -g @ace3/ace-cli

Or run directly:

npx @ace3/ace-cli

Quick Start

1. Launch the REPL:

   ace

2. Initialize a project:

   /init

3. Add content to the context tree:

   /curate

4. Scan for project patterns:

   /patterns scan

5. Query your knowledge base:

   /query testing best practices

6. Commit to git:

   git add .ace/
   git commit -m "Updated context tree"

Slash Commands

| Command | Description | |---------|-------------| | /status | Show project status | | /init [-f] | Initialize local project (git-based) | | /curate [context] [@files...] | Curate context interactively | | /query <terms> (or /q) | Query the context tree | | /index <build\|status\|clear> | Build and manage local context index | | /connectors | Manage agent connectors | | /patterns [scan\|list\|add] | Detect and manage project patterns | | /memory <put\|get\|search\|list\|forget\|compact> | Manage durable local memory | | /reset [-y] | Reset context tree | | /new [-y] | Clear REPL session | | /help [command] | Show help | | /exit | Exit the REPL |

Standalone CLI Commands

Run commands directly from the shell:

ace status [directory]         # Show project status
ace init [-f]                  # Initialize project
ace query <query>              # Query context tree
ace query <query> --mode hybrid --limit 20 # Query with lexical/semantic/hybrid mode
ace index build --scope context # Build incremental local index
ace index status               # Show index status
ace curate [context] [-f ...]   # Curate content
ace memory ...                 # Manage local agent memory
ace connectors sync --agent all # Sync memory into agent connector files

Pattern Detection

ACE can automatically scan your project and detect code patterns to enrich your context tree. This helps AI assistants understand your project's architecture, testing setup, and coding conventions.

Detected Pattern Types

| Type | Examples | |------|----------| | architecture | MVC, Clean Architecture, Layered, Repository, Service Layer | | framework | React, Express, NestJS, Next.js, Vue, Angular, Svelte | | code-style | TypeScript, JavaScript, Python, Go, Rust, Java, ESLint, Prettier | | testing | Jest, Vitest, Mocha, Pytest, Cypress, Playwright, Testing Library | | performance | Caching, Redis, Lazy loading, Virtualization | | security | Authentication, JWT, OAuth, Validation, Rate limiting, Helmet |

Pattern Commands

# Scan project for patterns (auto-detects from codebase)
ace patterns scan

# Scan specific pattern types only
ace patterns scan --types framework testing

# List all detected patterns
ace patterns list

# List patterns in JSON format
ace patterns list --json

# Add a manual pattern
ace patterns add "custom-pattern" --type architecture --description "My custom pattern"

# Remove a pattern
ace patterns remove architecture repository

# Clear all patterns
ace patterns clear --confirm

Pattern Output Example

Detected Patterns
────────────────────────────────────────

framework:
  ✓ nestjs - NestJS framework
     Confidence: [██████████] 95%
     Evidence: Found nestjs references
  ✓ react - React framework
     Confidence: [█████████░] 90%

code-style:
  ✓ typescript - TypeScript usage detected
     Confidence: [██████████] 95%
     Evidence: Found 105 .ts files, 10 .tsx files

architecture:
  ✓ repository - Repository pattern detected
     Confidence: [█████████░] 90%

Pattern Use Cases

1. Onboarding New Team Members

ace patterns scan
# Review detected patterns to understand project structure
# Use patterns to generate onboarding documentation

2. AI Assistant Context

# When asking AI assistants about your project, reference detected patterns:
# "I'm working with a NestJS project using Clean Architecture with Jest tests"

3. Compliance & Standards

# Verify all projects follow security patterns
ace patterns list --json | jq '.byType.security'

4. Project Migration

# Before migrating, scan to document current patterns
ace patterns scan --json > patterns-backup.json

# After migration, verify patterns are preserved
ace patterns scan

Pattern Storage

Patterns are stored in .ace/patterns.json and can be committed to git:

git add .ace/patterns.json
git commit -m "Update detected patterns"

Context Engine

ACE includes a local-only context engine optimized for retrieval quality and fast updates.

Index Commands

# Build index from context tree (default)
ace index build --scope context

# Include project files
ace index build --scope project

# Show index metadata
ace index status --json

# Clear index
ace index clear --confirm

Query Modes

# Lexical (exact-ish keyword match)
ace query "vitest setup" --mode lexical

# Semantic (meaning-based retrieval)
ace query "how should we test modules" --mode semantic

# Hybrid (recommended default)
ace query "testing strategy" --mode hybrid --limit 20

The context engine stores local index data in .ace/index/index.sqlite.

Project Structure

After initialization, your project will contain:

project/
├── .ace/
│   ├── config.json              # Project configuration
│   ├── .gitignore               # Ignores snapshot file
│   ├── patterns.json            # Detected patterns
│   └── context-tree/
│       ├── .snapshot.json       # Local state tracking
│       ├── code_style/
│       │   └── formatting/
│       │       └── context.md
│       ├── testing/
│       │   └── unit_tests/
│       │       └── context.md
│       └── ...

Context Tree Structure

• Domain - Top-level category (e.g., code_style, testing, structure)
• Topic - Specific area within a domain
• Subtopic - Optional sub-area (one level max)

Content is stored as Markdown with optional relations:

# Formatting Guidelines

Use 2-space indentation for all TypeScript files.

## Relations

See also @testing/unit_tests for test formatting rules.

Supported Agents

Configure connectors for these AI coding assistants:

| Agent | Rules | Hook | |-------|-------|------| | Amp | ✓ | | | Augment Code | ✓ | | | Claude Code | ✓ | ✓ | | Cline | ✓ | | | Codex | ✓ | | | Cursor | ✓ | | | Gemini CLI | ✓ | | | GitHub Copilot | ✓ | | | Junie | ✓ | | | Kilo Code | ✓ | | | Kiro | ✓ | |

Requirements

• Node.js 20+
• TTY terminal for REPL (interactive mode)
• Git for versioning your context tree

Platform Notes

All data is stored locally in .ace/ directory:

• macOS/Windows/Linux: Standard file system storage
• WSL: Same as Linux, uses standard file system

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

# Format
npm run format

Git Integration

The .ace/ directory is designed to be committed to git:

# Initialize git repository
git init

# Initialize ACE
ace
/init

# Commit your context tree
git add .ace/
git commit -m "Initialize ACE context tree"

# The .ace/.gitignore automatically excludes .snapshot.json

License

MIT

Publishing

See PUBLISHING.md for instructions on publishing this package to npm and creating releases.