/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
# 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, chunks large files, and uploads to the ACE batch-upload API. Uses incremental indexing with gzip JSON cache at `.ace-tool/index.json.gz`. Respects both `.gitignore` and `.aceignore` patterns. If a parent directory already has a `.ace-tool` cache (lookup stops before home / filesystem root), it is reused as the effective index root; child caches in subtrees covered by the root's scan are absorbed (deleted) after a successful index save. Concurrent runs need no locks: a save interrupted by a concurrent absorption abandons persistence (the next run inherits the ancestor root), and absorption skips caches it cannot delete, retrying on the next run. A 400 `unknown blobs` response during remote search triggers an automatic index rebuild, re-upload, and a single retry.

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 automatic local keyword fallback.

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 configuration is complete
• `token_configured` - Whether authentication token is set
• `third_party_configured` - Whether third-party endpoint config is complete
• `auth_source` - Authentication source: `constructor` | `session.json` | `AUGMENT_SESSION_AUTH` | `ACE_API_TOKEN` | `none`
• `search_context_injection` - Whether search context injection is enab