Skip to content

Dianel555/DSkills / skills/ace-tool

ace-tool

Verified

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 CLI

Semantic code search, incremental code indexing, and AI-powered prompt enhancement. MCP-independent CLI for codebase navigation and requirement clarification.

## Features

- **Code Indexing**: Incremental scan, hash (SHA-256), and upload whole files to the ACE service
- **Remote Search**: Semantic codebase retrieval via `POST /agents/codebase-retrieval` with local fallback
- **Prompt Enhancement**: AI-powered prompt refinement with interactive web UI
- **Cloud Context Injection**: All endpoints (old, new, third-party) inject retrieval context when `--project-root` is provided
- **Multiple Backends**: Support for Augment (`new`/`old`), Claude, OpenAI, Gemini, and Codex APIs
- **Search Context Injection**: Optional codebase context injection for third-party endpoints via XML tags
- **`.aceignore` Support**: Project-level exclusions in addition to root and nested `.gitignore` rules
- **Local Fallback**: Uses keyword-based search when remote retrieval is unavailable or returns no results

## Installation

```bash
pip install httpx tenacity "pathspec>=1.1.1,<2"
```

## Quick Start

### Authentication Setup

**Recommended: Use session.json (compatible with auggie CLI)**

```bash
# If you have auggie CLI installed, just login:
auggie login

# This creates ~/.augment/session.json with your credentials
```

**Alternative: Environment Variable (for CI/CD)**

```bash
export AUGMENT_SESSION_AUTH='{"accessToken":"your-token","tenantURL":"https://api.example.com/"}'
```

**Legacy Method (deprecated but still supported)**

```bash
export ACE_API_URL="https://your-api-endpoint.com"
export ACE_API_TOKEN="your-token-here"
```

### Basic Usage

```bash
# Index project (scan, hash, upload code blobs)
python scripts/ace_cli.py index -p .

# Search codebase (remote retrieval if API configured, else local fallback)
python scripts/ace_cli.py search_context -p . -q "user authentication handler"

# Enhance prompt (opens interactive web UI)
python scripts/ace_cli.py enhance_prompt -p "implement login feature" --project-root .

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

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

# Show configuration (check auth_source to verify authentication method)
python scripts/ace_cli.py get_config
```
## CLI Commands

### Indexing
| Command | Description |
|---------|-------------|
| `index -p <path>` | Index project: scan, hash, and upload whole files |

### Search Operations
| Command | Description |
|---------|-------------|
| `search_context -p <path> -q <query>` | Search codebase with natural language |

### Enhancement Operations
| Command | Description |
|---------|-------------|
| `enhance_prompt -p <prompt>` | Enhance prompt (interactive UI) |
| `enhance_prompt --no-interactive -p <prompt>` | Enhance prompt (JSON output) |
| `enhance_prompt -H <history> -p <prompt>` | Enhance with conversation history |
| `enhance_prompt --project-root <path> -p <prompt>` | Enhance with cloud code context |

### Configuration
| Command | Description |
|---------|-------------|
| `get_config` | Show current configuration |

## Global Options

```bash
python scripts/ace_cli.py [OPTIONS] <command>

Options:
  --endpoint TYPE       API endpoint: new, old, claude, openai, gemini, codex
  --api-url URL         Override API base URL
  --token TOKEN         Override API token
```

## Endpoint Architecture

### Supported Endpoints

| Endpoint | API Path | Default Model | Type | Status |
|----------|----------|---------------|------|--------|
| `new` | `/prompt-enhancer` | `claude-sonnet-4-5` | Augment | ⚠️ Currently unavailable |
| `old` | `/chat-stream` (SSE) | `claude-sonnet-4-5` | Augment | ⚠️ Currently unavailable |
| `claude` | `/v1/messages` | `sonnet-4-6-20250929` | Third-party | ✅ Available |
| `openai` | `/v1/chat/completions` | `gpt-5.4` | Third-party | ✅ Available |
| `gemini` | `/v1beta/models/{model}:generateContent` | `gemini-3-flash-preview` | Third-party | ✅ Available |
| `codex` | `/v1/responses` | `gpt-5.4` | Third-party | ✅ Available |

> **Note**: The official Augment endpoints (`new` and `old`) are currently experiencing service issues. Please use third-party endpoints (Claude, OpenAI, Gemini, or Codex) for prompt enhancement features.

### Endpoint Resolution

Priority order (highest wins):

1. `PROMPT_ENHANCER_ENDPOINT` env var
2. `ACE_ENHANCER_ENDPOINT` env var (legacy fallback)
3. `--endpoint` CLI flag
4. Default: `new`

### Codex Endpoint

The `codex` endpoint routes to OpenAI's Responses API (`/v1/responses`). It uses the `input`/`output` array format instead of the Chat Completions `messages` format. Response parsing handles `output_text` content parts, `final_answer` phase priority, and refusal detection.

```bash
export PROMPT_ENHANCER_ENDPOINT=codex
export PROMPT_ENHANCER_BASE_URL=https://api.openai.com
export PROMPT_ENHANCER_TOKEN=sk-...
python scripts/ace_cli.py enhance_prompt -p "implement feature"
```

### URL Construction

All HTTP calls use `build_api_url(base_url, path)` which handles version prefix deduplication (e.g., `https://api.example.com/v1` + `/v1/messages` → `https://api.example.com/v1/messages`, not `.../v1/v1/messages`).

## Configuration

### Authentication

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)

**Method 1: session.json (Recommended)**

Use `auggie login` to create `~/.augment/session.json`:
```json
{
  "accessToken": "your-token-here",
  "tenantURL": "https://api.example.com/",
  "scopes": ["email"]
}
```

**Method 2: AUGMENT_SESSION_AUTH (CI/CD)**

```bash
export AUGMENT_SESSION_AUTH='{"accessToken":"your-token","tenantURL":"https://api.example.com/"}'
```

**Method 3: Legacy Environment Variables (Deprecated)**

```bash
export ACE_API_URL=https://your-augment-api.com
export ACE_API_TOKEN=your-augment-token
```

⚠️ **Note**: `ACE_API_URL` and `ACE_API_TOKEN` are deprecated but still supported for backward compatibility. New projects should use `session.json` or `AUGMENT_SESSION_AUTH`.

**Verify Configuration**

Use `get_config` to check current authentication source:
```bash
python scripts/ace_cli.py get_config
# Output includes: "auth_source": "session.json" | "AUGMENT_SESSION_AUTH" | "ACE_API_TOKEN" | "none"
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `AUGMENT_SESSION_AUTH` | JSON string with `accessToken` and `tenantURL` (new format, recommended for CI/CD) |
| `ACE_API_URL` | ⚠️ **Deprecated** - Augment API base URL (use session.json or AUGMENT_SESSION_AUTH instead) |
| `ACE_API_TOKEN` | ⚠️ **Deprecated** - Augment API token (use session.json or AUGMENT_SESSION_AUTH instead) |
| `PROMPT_ENHANCER_ENDPOINT` | Endpoint type override (takes precedence over `ACE_ENHANCER_ENDPOINT`) |
| `ACE_ENHANCER_ENDPOINT` | Legacy endpoint override (fallback) |
| `PROMPT_ENHANCER_BASE_URL` | Third-party API base URL |
| `PROMPT_ENHANCER_TOKEN` | Third-party API key |
| `PROMPT_ENHANCER_MODEL` | Model override for third-party endpoints |
| `PROMPT_ENHANCER_INCLUDE_SEARCH_CONTEXT` | Enable search context injection (`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) |

For slow synchronous embedding, increase the read timeout and/or reduce batch size. The byte budget measures file content only, excluding JSON and HTTP overhead; each blob must fit within it. Settings must be positive and finite. Read/write and other uncertain transport errors, or HTTP 408, 429, and 5xx responses, trigger `/agents/blob-status` polling before any 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. If status remains uncertain or unavailable, the client automatically retries up to three potentially sent attempts per blob, tracked across process restarts. The server may still be processing an earlier request, so duplicate server work is possible. Exhausted attempts, authentication failures, and unsafe recovery state produce explicit errors; no manual prompt is shown.

### .env File

Create `.env` in the project root (see `.env.example`):

```bash
# Recommended: Use ~/.augment/session.json (created by `auggie login`)
# or set AUGMENT_SESSION_AUTH for CI/CD

# Legacy format (deprecated)
# ACE_API_URL=https://your-augment-api.com
# ACE_API_TOKEN=your-augment-token

PROMPT_ENHANCER_ENDPOINT=new

# Third-party API (optional)
# PROMPT_ENHANCER_BASE_URL=https://api.anthropic.com
# PROMPT_ENHANCER_TOKEN=your-api-key
# PROMPT_ENHANCER_MODEL=sonnet-4-6-20250929

# Search context injection (optional, for third-party endpoints)
# PROMPT_ENHANCER_INCLUDE_SEARCH_CONTEXT=1
```

## Search Context Injection

When `PROMPT_ENHANCER_INCLUDE_SEARCH_CONTEXT` is enabled and a third-party endpoint is used, the system:

1. Searches the codebase via ACE API using the original prompt as query
2. Normalizes the result (placeholder if empty, truncates at 12,000 chars)
3. Wraps 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

Requirements:
- `--project-root` must be provided (raises `ValueError` otherwise)
- `ACE_API_URL` and `ACE_API_TOKEN` must be configured

This is separate from the cloud retrieval context that Augment endpoints (`new`/`old`) inject automatically via `--project-root`.

## .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/
```
## Indexing Details

The `index` command performs incremental indexing:

- **Scan**: Walks project files filtered by extension whitelist, binary blacklist, `.gitignore` + `.aceignore` patterns (with glob support), and `EXCLUDE_PATTERNS`
- **Hash**: `SHA-256(path_bytes + content_bytes)` per blob
- **Files**: Uploads each file up to 128 KiB with its original path; any chunking is performed by the service.
- **Cache**: Incremental via `mtime + size` check; stored as `.ace-tool/index.json.gz`. Legacy chunk-based caches are rebuilt once.
- **Hierarchy**: The supplied project root is the index and upload boundary. Each root keeps its own cache; indexing a parent does not delete child caches.
- **Boundary**: Symbolic links, junctions and other reparse points below the root are never followed, and the index cache is read and written through a verified handle. Only real files inside the root are read and uploaded; a link, an out-of-boundary path or an oversized cache is skipped or rebuilt rather than followed.
- **Recovery and concurrency**: A per-project OS lock serializes cooperating processes through cache publication. `.ace-tool/upload-journal.json` stores blob hashes, hashed service origins and API path prefixes, and attempt state before uploads, but no file contents or tokens. API URL paths must contain only non-secret prefixes: credentials belong in the separate token configuration, not in URLs. Configured tokens in URL paths are rejected, but arbitrary secrets in paths cannot be detected automatically. Blobs are checked with current credentials before upload; confirmed ready blobs are reused, while unresolved blobs are retried within the persistent attempt budget. Acknowledged entries are compacted from the journal; uncertain entries and their attempt counts are retained. If the 64 MiB journal cannot accommodate unresolved entries, uploads stop with an explicit error. 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.
- **Readiness**: Indexing, search and project-scoped prompt enhancement poll `POST /agents/blob-status` before using blobs, with a 3-minute polling deadline and per-request network timeouts. Unsupported or invalid status responses are errors, not empty search results.
- **Retrieval timeout**: Remote retrieval allows up to 2 minutes per network read, with a 15-second connection timeout; readiness has a separate 3-minute deadline.
- **Empty results**: Empty remote retrieval (including OCE's header-only response) falls back to local keyword matching. Local prompt context contains matching file paths, not semantic code snippets.
- **Self-heal**: Unknown blobs trigger one full rescan, with status checks before re-uploading missing blobs, followed by a readiness check; a subsequent unknown-blob error is reported.
- **Upload**: Batch upload (≤30 blobs, ≤1 MiB of content per batch) to `POST /batch-upload`. Confirmed connection failures are retried; 401/403 abort. Ambiguous results are checked through blob status and may be retried automatically within the persistent budget; 429 waits for the bounded `Retry-After` delay before reconciliation. A successful upload response must confirm every expected SHA-256 blob name.
- **Failure**: An upload failure raises an error and leaves the previous cache on disk unchanged; stale entries are not returned as successful results.
- **Encoding**: Multi-encoding detection chain (`utf-8 → gbk → gb18030 → cp1252`)

## Output Format

All CLI output is JSON:

```json
// Index result
{"total_blobs": 42, "last_indexed": 1234567890.0, "project_root": "."}

// Search result (remote)
{"results": "formatted retrieval text...", "query": "...", "mode": "remote", "blob_count": 42}

// Search result (local fallback)
{"results": [{"file": "src/auth.py", "score": 5}], "query": "...", "mode": "local_fallback"}

// Enhancement result
{"enhanced_prompt": "..."}

// Configuration
{"base_url": "...", "endpoint": "new", "endpoint_effective": "new", "endpoint_env_ready": true, "token_configured": true, "third_party_configured": false, "search_context_injection": false}

// Error
{"error": "message", "status_code": 401}
```

## Project Structure

```
skills/ace-tool/
├── SKILL.md              # Agent instructions
├── README.md             # Developer documentation
└── scripts/
    ├── .env.example      # Environment template
    ├── __init__.py
    ├── __main__.py       # Module entry point
    ├── ace_cli.py        # CLI entry point
    ├── client.py         # API client (search, enhance, retrieval, all endpoints)
    ├── indexer.py         # Code indexer (scan, hash, upload, .aceignore)
    ├── templates.py      # Prompt templates and constants
    ├── utils.py          # Utilities (encoding detection, content sanitization)
    └── web_ui.py         # Interactive web UI
```

## Acknowledgments

- Based on [missdeer/ace-tool-rs](https://github.com/missdeer/ace-tool-rs)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall