/ace-tool

name: ace-tool
description: |
  Semantic codebase search, code indexing, and prompt enhancement via standalone CLI. Use when: (1) Semantic code search with natural language queries, (2) Code indexing for remote codebase retrieval, (3) Prompt enhancement with codebase context, (4) Before grep/find/glob operations for better accuracy, (5) Complex requirements clarification, (6) Large codebase navigation. Triggers: "search context", "enhance prompt", "find code that", "index project", "clarify requirements". IMPORTANT: Always use ace-tool BEFORE grep/find/glob for semantic-level code location.

ACE-Tool - Semantic Code Search & Prompt Enhancement

High-performance semantic search, code indexing, and AI-powered prompt enhancement. Standalone CLI (no MCP dependency).

Execution Methods

# Prerequisites: pip install httpx tenacity "pathspec>=1.1.1,<2"
# Environment: ACE_API_URL, ACE_API_TOKEN (optional for local fallback)

# Index project for remote search (upload code blobs to ACE service)
python scripts/ace_cli.py index -p /path/to/project

# Search codebase with natural language (remote if API configured, else local fallback)
python scripts/ace_cli.py search_context -p /path/to/project -q "function that handles authentication"

# Enhance prompt (interactive mode - default, opens browser)
python scripts/ace_cli.py enhance_prompt -p "implement login feature" -H "User: what auth method?\nAssistant: JWT"

# Enhance prompt (non-interactive, JSON output)
python scripts/ace_cli.py enhance_prompt --no-interactive -p "implement login feature"

# Enhance prompt with project context (enables cloud retrieval for all endpoints)
python scripts/ace_cli.py enhance_prompt -p "implement login feature" --project-root /path/to/project

# Enhance prompt with specific endpoint
python scripts/ace_cli.py --endpoint claude enhance_prompt -p "implement login feature"

# Enhance prompt with codex endpoint
python scripts/ace_cli.py --endpoint codex enhance_prompt -p "implement feature"

# Check configuration
python scripts/ace_cli.py get_config

Tool Routing Policy

Prefer ACE-Tool Over Built-in Tools

| Task | Avoid | Use ACE-Tool CLI | |------|-------|------------------| | Find function by purpose | `grep "def func"` | `search_context -q "function that..."` | | Locate feature code | `find . -name "*.py"` | `search_context -q "feature description"` | | Clarify requirements | Manual analysis | `enhance_prompt -p "requirement"` | | Understand code flow | Multiple grep/read | `search_context -q "flow description"` | | Index codebase | N/A | `index -p <project_root>` |

When to Use Built-in Tools

• Exact string matching (known identifiers)
• File path patterns (known naming conventions)
• Simple text replacement

Command Reference

index

Index project files for remote codebase retrieval. Scans, hashes, and uploads whole files (up to 128 KiB) with their original paths to the ACE batch-upload API; chunking is left to the service. Uses incremental indexing with gzip JSON cache at `.ace-tool/index.json.gz`; legacy chunk-based caches are rebuilt once. Respects both `.gitignore` and `.aceignore` patterns. The supplied project root is the index and upload boundary; each root keeps its own cache, and indexing a parent does not delete child caches. Symbolic links, junctions and other reparse points below the root are never followed, so only real files inside the root are read and uploaded; an unreadable or out-of-boundary path is skipped instead of falling back to a plain path read. The backend must confirm upload hashes and support the OCE-compatible `/agents/blob-status` endpoint; indexing, search, and scoped enhancement wait for readiness and report a timeout or unsupported status explicitly. Unknown blobs trigger one rebuild and re-upload.

python scripts/ace_cli.py index -p <project_root>

Options:
  -p, --project-root    Project root path (required)

search_context

Search codebase using natural language descriptions. Routes to remote API (`POST /agents/codebase-retrieval`) when configured, with local keyword fallback for remote errors or empty results. Upload and readiness failures remain explicit errors. Local fallback supplies matching file paths, not semantic code snippets.

python scripts/ace_cli.py search_context -p <project_root> -q <query>

Options:
  -p, --project-root    Project root path (required)
  -q, --query           Natural language query (required)

enhance_prompt

Enhance prompts with codebase context and conversation history. All endpoints inject cloud retrieval context when `--project-root` is provided. Third-party endpoints additionally support search context injection via `PROMPT_ENHANCER_INCLUDE_SEARCH_CONTEXT`.

python scripts/ace_cli.py [--endpoint TYPE] enhance_prompt -p <prompt> [options]

Global Options:
  --endpoint            Endpoint type: new, old, claude, openai, gemini, codex (default: new)
  --api-url             Override API base URL
  --token               Override API token

Command Options:
  -p, --prompt          Original prompt (required)
  -H, --history         Conversation history: "User: xxx\nAssistant: yyy"
  --history-file        File containing conversation history
  --project-root        Project root path (enables cloud retrieval context)
  --no-interactive      Disable web UI, output JSON directly
  --no-browser          Don't auto-open browser, just print URL
  --port                Port for web server (default: 8765)

get_config

Show current configuration status including endpoint resolution, env readiness, authentication source, and search context injection state.

python scripts/ace_cli.py get_config

**Output fields:**

• `base_url` - Currently configured API base URL
• `endpoint` - Active enhancer endpoint (new/old/claude/openai/gemini/codex)
• `endpoint_effective` - Resolved endpoint after env variable resolution
• `endpoint_env_ready` - Whether required endpoint config