ace-tool

# 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

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

```bash
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.

```bash
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`.

```bash
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, and search context injection state.

```bash
python scripts/ace_cli.py get_config
```

Output fields: `base_url`, `endpoint`, `endpoint_effective`, `endpoint_env_ready`, `token_configured`, `third_party_configured`, `search_context_injection`.
## 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

## Endpoint Architecture

### Supported Endpoints

| Endpoint | API Path | Default Model | Auth Header |
|----------|----------|---------------|-------------|
| `new` | `/prompt-enhancer` | `claude-sonnet-4-5` | `Bearer ACE_API_TOKEN` |
| `old` | `/chat-stream` (SSE) | `claude-sonnet-4-5` | `Bearer ACE_API_TOKEN` |
| `claude` | `/v1/messages` | `sonnet-4-6-20250929` | `x-api-key` |
| `openai` | `/v1/chat/completions` | `gpt-5.4` | `Bearer PROMPT_ENHANCER_TOKEN` |
| `gemini` | `/v1beta/models/{model}:generateContent` | `gemini-3-flash-preview` | `x-goog-api-key` |
| `codex` | `/v1/responses` | `gpt-5.4` | `Bearer PROMPT_ENHANCER_TOKEN` |

### Endpoint Resolution Order

`PROMPT_ENHANCER_ENDPOINT` > `ACE_ENHANCER_ENDPOINT` (legacy) > `--endpoint` CLI flag > `new` (default)

### Third-Party Endpoints

`claude`, `openai`, `gemini`, `codex` are third-party endpoints. They require:
- `PROMPT_ENHANCER_BASE_URL` — API base URL
- `PROMPT_ENHANCER_TOKEN` — API key/token
- `PROMPT_ENHANCER_MODEL` — (optional) override default model

Missing configuration raises `ValueError` immediately (hard error, no silent fallback).

### URL Construction

All HTTP calls use