ace-tool git:20261103.fa935e6A

Immutable. This exact content never changes and is served at /api/v1/blob/2c4c55cd45593901.

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

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

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

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

```bash
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 enabled
## 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 | Status |
|----------|----------|---------------|-------------|--------|
| `new` | `/prompt-enhancer` | `claude-sonnet-4-5` | `Bearer ACE_API_TOKEN` | ⚠️ Currently unavailable |
| `old` | `/chat-stream` (SSE) | `claude-sonnet-4-5` | `Bearer ACE_API_TOKEN` | ⚠️ Currently unavailable |
| `claude` | `/v1/messages` | `sonnet-4-6-20250929` | `x-api-key` | ✅ Available |
| `openai` | `/v1/chat/completions` | `gpt-5.4` | `Bearer PROMPT_ENHANCER_TOKEN` | ✅ Available |
| `gemini` | `/v1beta/models/{model}:generateContent` | `gemini-3-flash-preview` | `x-goog-api-key` | ✅ Available |
| `codex` | `/v1/responses` | `gpt-5.4` | `Bearer PROMPT_ENHANCER_TOKEN` | ✅ Available |

> **Note**: The official Augment endpoints (`new` and `old`) are currently experiencing service issues. Use third-party endpoints for prompt enhancement.

### 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 `build_api_url(base_url, path)` which handles `/v1/`, `/v1beta/` version prefix deduplication. No hardcoded f-string URL construction.

## Environment Variables

### Authentication (Priority Order)

ACE-Tool supports multiple authentication methods with the following priority:

1. **Constructor parameters** (highest priority, programmatic use only)
2. **`~/.augment/session.json`** (recommended, created by `auggie login`)
3. **`AUGMENT_SESSION_AUTH`** (CI/CD and headless environments)
4. **Legacy `ACE_API_*`** (deprecated, backward compatibility only)

| Variable | Description |
|----------|-------------|
| `AUGMENT_SESSION_AUTH` | JSON string with `accessToken` and `tenantURL` (new format, recommended for CI/CD) |
| `ACE_API_URL` | ⚠️ **Deprecated** - ACE API base URL (use session.json or AUGMENT_SESSION_AUTH instead) |
| `ACE_API_TOKEN` | ⚠️ **Deprecated** - ACE API authentication token (use session.json or AUGMENT_SESSION_AUTH instead) |

**Recommended: Use `~/.augment/session.json`**

Create this file via `auggie login`, or manually with this format:
```json
{
  "accessToken": "your-token-here",
  "tenantURL": "https://api.example.com/",
  "scopes": ["email"]
}
```

**For CI/CD: Use `AUGMENT_SESSION_AUTH` environment variable**
```bash
export AUGMENT_SESSION_AUTH='{"accessToken":"token","tenantURL":"https://api.example.com/"}'
```

**Migration Guide: Legacy to New Format**

If currently using `ACE_API_URL` and `ACE_API_TOKEN`:

1. **Option A** (Recommended): Use `auggie login` to create `~/.augment/session.json`
2. **Option B**: Convert to `AUGMENT_SESSION_AUTH`:
   ```bash
   export AUGMENT_SESSION_AUTH='{"accessToken":"YOUR_ACE_API_TOKEN","tenantURL":"YOUR_ACE_API_URL"}'
   ```
3. Remove old variables (optional, they'll be ignored if new format exists)

Legacy variables continue to work for backward compatibility but are not recommended for new setups.

### Endpoint Configuration

| Variable | Description |
|----------|-------------|
| `PROMPT_ENHANCER_ENDPOINT` | Endpoint override: `new`, `old`, `claude`, `openai`, `gemini`, `codex` |
| `ACE_ENHANCER_ENDPOINT` | Legacy endpoint override (fallback if `PROMPT_ENHANCER_ENDPOINT` not set) |
| `PROMPT_ENHANCER_BASE_URL` | Third-party API base URL (for claude/openai/gemini/codex endpoints) |
| `PROMPT_ENHANCER_TOKEN` | Third-party API token |
| `PROMPT_ENHANCER_MODEL` | Override default model for third-party endpoints |
| `PROMPT_ENHANCER_INCLUDE_SEARCH_CONTEXT` | Enable search context injection for third-party endpoints (`1`, `true`, `yes`, `on`) |
| `ACE_UPLOAD_READ_TIMEOUT_SECONDS` | Upload response read inactivity timeout in seconds (default: 300) |
| `ACE_UPLOAD_BATCH_COUNT` | Maximum blobs per batch (default/maximum: 30) |
| `ACE_UPLOAD_BATCH_BYTES` | Maximum UTF-8 content bytes per batch (default/maximum: 1048576) |

Settings are positive and finite. The byte budget counts content only, excluding JSON/HTTP overhead, and each blob must fit within it. Read/write and other uncertain transport errors, or HTTP 408, 429, and 5xx responses, trigger `/agents/blob-status` polling before retransmission. Previously uncertain blobs receive a 5-second grace period when status is unknown; pending blobs are polled up to 180 seconds. These are not strict wall-clock limits because HTTPX read timeouts measure inactivity. When status remains uncertain or unavailable, unresolved blobs are retried automatically up to three potentially sent attempts per blob across process restarts. The server may still be processing an earlier request, so this does not guarantee exactly-once server work. Exhausted attempts, authentication failures, and unsafe recovery state produce explicit errors.

A per-project OS lock serializes cooperating processes through index publication. `.ace-tool/upload-journal.json` stores blob hashes, hashed service origins and API path prefixes, and attempt state, not file contents or tokens. URL paths must contain only non-secret API prefixes; configure credentials separately. Configured tokens in paths are rejected, but arbitrary path secrets cannot be detected automatically. Blobs are checked with current credentials before upload and ready blobs are reused. Acknowledged entries are compacted; uncertain entries and their attempt counts are retained. Uploads fail explicitly if unresolved entries exceed the 64 MiB journal limit. The persistent `.ace-tool.lock` marker rejects mixed Windows and POSIX/WSL access to the same project root; use a separate root for each platform.

## Search Context Injection

When `PROMPT_ENHANCER_INCLUDE_SEARCH_CONTEXT` is enabled and a third-party endpoint is used, the system automatically:
1. Performs a remote codebase search via ACE API using the original prompt as query
2. Normalizes the result (placeholder if empty, truncate at 12000 chars if too long)
3. Wraps the search results in `<codebase_context>` XML tags
4. Wraps the original prompt in `<original_request>` XML tags
5. Sends the combined prompt to the third-party LLM

Requires `--project-root` and valid `ACE_API_URL`/`ACE_API_TOKEN`. Raises `ValueError` if `project_root` is missing when injection is enabled.

## .aceignore

Project-root and nested `.gitignore` files apply with Git's directory-relative pattern precedence. A project-root `.aceignore` uses the same glob syntax as an independent, additional exclusion filter: its negations can override earlier `.aceignore` rules but cannot re-include files excluded by `.gitignore`. Both filters also apply to local fallback; an ignored parent directory cannot be re-included by a child pattern.

```
# .aceignore example
test_fixtures/
*.generated.ts
large_data/
node_modules/
.*/
logs/
tests/
```
## Workflow

### Phase 0: Index Project (once or after major changes)
```bash
index -p .                                            # Upload code blobs to ACE
```

### Phase 1: Semantic Search
```bash
search_context -p . -q "database connection pooling"  # Remote retrieval or local fallback
```

### Phase 2: Prompt Enhancement
```bash
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

```json
{"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 | Report an error; keep the previous cache on disk without returning its stale blobs |
| Connection timeout | Retries up to 3 times with exponential backoff |
| No results | Broaden search query |
| Third-party not configured | `ValueError` raised immediately (no silent fallback) |
| Search context missing project_root | `ValueError` raised when injection enabled without `--project-root` |

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