ACE-Tool - Semantic Code Search & Prompt Enhancement Skill

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"

# 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.

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 (old, new, third-party) inject cloud retrieval context when --project-root is provided.

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

Global Options:
  --endpoint            Endpoint type: new, old, claude, openai, gemini (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.

python scripts/ace_cli.py get_config

Interactive Enhancement

Default mode opens web UI with actions:

| Button | Action | |--------|--------| | Regenerate | Discard current, generate new enhancement from original prompt | | Refine | Iteratively improve current version, preserving your edits | | Use Original | Return the original prompt without enhancement | | Send Enhanced | Confirm and use the current enhanced prompt | | Cancel | Abort the enhancement process |

Keyboard Shortcuts: Ctrl+Enter Send | Esc Cancel

Workflow

Phase 0: Index Project (once or after major changes)

index -p .                                            # Upload code blobs to ACE

Phase 1: Semantic Search

search_context -p . -q "database connection pooling"  # Remote retrieval or local fallback

Phase 2: Prompt Enhancement

enhance_prompt -p "optimize query performance" --project-root .  # With cloud context
# Review and refine enhanced prompt
# Use Regenerate/Refine as needed
# Send Enhanced to confirm

Error Handling

{"error": "error message", "status_code": 401}

| Error | Recovery | |-------|----------| | No API configured | Uses local fallback for search_context; returns original for enhance | | Token invalid (401) | Check API token (logged at ERROR level) | | Access denied (403) | Token may be disabled (logged at ERROR level) | | Upload failure | Index rollback to previous state; cached blobs still returned | | Connection timeout | Retries up to 3 times with exponential backoff | | No results | Broaden search query |

Anti-Patterns

| Prohibited | Correct | |------------|---------| | Grep before semantic search | Use search_context first | | Skip prompt enhancement | Use enhance_prompt for complex tasks | | Ignore conversation history | Include history in enhance_prompt | | Use exact match for conceptual search | Use natural language query | | Always use non-interactive mode | Use interactive mode for review | | Skip --project-root for enhance | Include it for cloud-based code context |

Agent Skills: ACE-Tool - Semantic Code Search & Prompt Enhancement

Install this agent skill to your local

Skill Files