gh-ce-dot-net-ce-claude-marketplace-plugins-ace/commands/ace-tune.md

---
description: View and update ACE project configuration dynamically at runtime
---

# ACE Configuration Management (Project-Level)

Manage ACE configuration for **THIS PROJECT ONLY**. Adjust thresholds, enable token budget, and configure runtime behavior dynamically.

## 🚨 Important: Project-Level Scope

**All `/ace-tune` commands affect THIS PROJECT ONLY.**

- Changes apply to the current project
- Other projects in your organization are NOT affected
- Organization-wide settings are managed via web dashboard

**Hierarchical Configuration:**
- **Server defaults** (global baseline)
- **Organization-level** (per org) ← Set via web dashboard
- **Project-level** (per project) ← `/ace-tune` scope

**Priority**: `Project > Org > Server` (project overrides org overrides server)

**For organization-wide configuration**, use the web dashboard instead.

## What This Does

Allows you to **fetch and update ACE project configuration** in real-time:
- View current effective configuration (with source hierarchy)
- Enable/disable token budget enforcement for this project
- Adjust semantic search sensitivity
- Configure deduplication thresholds
- Control automatic learning features
- Reset project config to org/server defaults

**All changes persist on the server** for this specific project.

## Instructions for Claude

When the user runs `/ace-tune [action] [params]`, execute the tune script:

### 1. View Current Configuration

```bash
#!/usr/bin/env bash
set -euo pipefail

# Get plugin root directory
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"

# Execute tune script - shows current config
exec "${PLUGIN_ROOT}/scripts/ace-tune.sh" show
```

**Display format:**
```
┌─────────────────────────────────────────────────────┐
│ ACE Configuration (Project: {project_name})         │
├─────────────────────────────────────────────────────┤
│ dedup_similarity_threshold: 0.85 (from org)         │
│ constitution_threshold: 0.7 (from server)           │
│ pruning_threshold: 0.3 (from server)                │
│ token_budget_enforcement: false (from server)       │
│ max_playbook_tokens: null (from server)             │
│ max_batch_size: 50 (from server)                    │
│ auto_learning_enabled: true (from server)           │
│ reflector_enabled: true (from server)               │
│ curator_enabled: true (from server)                 │
│ dedup_enabled: true (from server)                   │
│                                                     │
│ 💡 Config source: project < org < server           │
│    To change org defaults, use web dashboard.      │
└─────────────────────────────────────────────────────┘
```

**Returns current effective settings including:**
- `constitution_threshold` - Semantic search threshold (default: 0.7)
- `dedup_similarity_threshold` - Duplicate detection threshold (default: 0.85)
- `pruning_threshold` - Low-quality pattern removal (default: 0.3)
- `token_budget_enforcement` - Auto-pruning enabled/disabled (default: false)
- `max_playbook_tokens` - Token limit before pruning (default: null)
- `max_batch_size` - Max patterns per batch request (default: 50)

### 2. Interactive Mode (Recommended)

When user runs `/ace-tune` without arguments, use AskUserQuestion tool for interactive configuration:

```python
# Step 1: Show current config first
ce-ace tune show

# Step 2: Ask what they want to change
AskUserQuestion({
  "questions": [{
    "question": "What would you like to configure?",
    "header": "ACE Setting",
    "multiSelect": false,
    "options": [
      {
        "label": "Search Threshold",
        "description": "Adjust similarity threshold for pattern retrieval (0.0-1.0)"
      },
      {
        "label": "Search Top K",
        "description": "Maximum patterns returned per search (1-100)"
      },
      {
        "label": "Token Budget",
        "description": "Enable automatic playbook pruning at token limit"
      },
      {
        "label": "View Only",
        "description": "Just show current configuration"
      }
    ]
  }]
})

# Step 3: Based on selection, ask for value
# Example: If "Search Threshold" selected
AskUserQuestion({
  "questions": [{
    "question": "What threshold value? (0.0-1.0)",
    "header": "Threshold",
    "multiSelect": false,
    "options": [
      {"label": "0.35", "description": "Broad matches (more results)"},
      {"label": "0.45", "description": "Balanced (recommended)"},
      {"label": "0.60", "description": "Strict matches (fewer results)"},
      {"label": "0.75", "description": "Very strict (only close matches)"}
    ]
  }]
})

# Step 4: Apply with CLI
ce-ace tune --constitution-threshold 0.45
```

### 3. Non-Interactive Mode (Direct)

```bash
# Single setting
ce-ace tune --constitution-threshold 0.6

# Multiple settings
ce-ace tune \
  --constitution-threshold 0.5 \
  --search-top-k 15 \
  --dedup-enabled true
```

**What this does**:
- Enables automatic playbook pruning FOR THIS PROJECT
- When playbook exceeds 50,000 tokens:
  - Server removes low-quality patterns (helpful-harmful < pruning_threshold)
  - Keeps high-quality patterns
  - Maintains playbook size within budget

### 3. Direct CLI Examples

**Adjust Search Threshold**:
```bash
# Lower threshold for broader matches
ce-ace tune --constitution-threshold 0.35

# Higher threshold for stricter matches
ce-ace tune --constitution-threshold 0.8
```

**Effect on `/ace-search`**:
- **Lower (0.3-0.5)**: Broader matches, more results
- **Medium (0.6-0.7)**: Balanced precision/recall
- **Higher (0.8-0.9)**: Stricter matches, fewer but more precise results

**Adjust Multiple Settings**:
```bash
# Configure search behavior
ce-ace tune \
  --constitution-threshold 0.5 \
  --search-top-k 15

# Configure deduplication
ce-ace tune --dedup-similarity-threshold 0.9

# Configure pruning
ce-ace tune --pruning-threshold 0.4

# Enable token budget
ce-ace tune --token-budget-enforcement true --max-playbook-tokens 50000
```

**Reset to Defaults**:
```bash
# Reset project to org/server defaults
ce-ace tune --reset

# Verify reset
ce-ace tune show
```

## Configuration Options Reference

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| `constitution_threshold` | float | 0.7 | 0.0-1.0 | Semantic search similarity threshold |
| `dedup_similarity_threshold` | float | 0.85 | 0.0-1.0 | Duplicate detection threshold |
| `pruning_threshold` | float | 0.3 | 0.0-1.0 | Min quality score to keep pattern |
| `token_budget_enforcement` | bool | false | - | Enable automatic pruning |
| `max_playbook_tokens` | int\|null | null | >0 | Token limit for auto-pruning |
| `max_batch_size` | int | 50 | 1-100 | Max patterns per batch request |
| `auto_learning_enabled` | bool | true | - | Enable automatic learning |
| `reflector_enabled` | bool | true | - | Enable Reflector (Sonnet 4) |
| `curator_enabled` | bool | true | - | Enable Curator (Haiku 4.5) |
| `dedup_enabled` | bool | true | - | Enable deduplication |

## Common Use Cases

### Optimize for Precision (Strict Search)

```bash
/ace-tune search-threshold 0.85
```
**Use when**: You want only highly relevant results for this project, willing to miss some edge cases.

### Optimize for Recall (Broad Search)

```bash
/ace-tune search-threshold 0.4
```
**Use when**: You want comprehensive results for this project, okay with some less-relevant matches.

### Enable Automatic Playbook Management

```bash
/ace-tune token-budget 50000
```
**Use when**: This project's playbook is growing large (10k+ patterns) and you want automatic quality-based pruning.

### Aggressive Deduplication

```bash
/ace-tune dedup-threshold 0.75
```
**Use when**: This project is getting too many similar patterns and you want more aggressive merging.

### Conservative Pruning

```bash
/ace-tune pruning-threshold 0.2
```
**Use when**: Token budget is enabled for this project but you want to keep more patterns (only remove clearly harmful ones).

### Reset to Organization Defaults

```bash
/ace-tune reset
```
**Use when**: You want to remove project-specific customizations and inherit org/server defaults.

## Example Workflows

### Interactive Mode (Recommended for Exploration)

```
User: "/ace-tune"
Claude: [Shows current config via ce-ace tune show]
Claude: [Uses AskUserQuestion with options: Search Threshold, Search Top K, Token Budget, View Only]
User: Selects "Search Threshold"
Claude: [Uses AskUserQuestion with threshold options: 0.35, 0.45, 0.60, 0.75]
User: Selects "0.45"
Claude: [Runs ce-ace tune --constitution-threshold 0.45]
Claude: "✅ Search threshold updated to 0.45 for this project"
```

### Non-Interactive Mode (Fast Direct Changes)

```bash
# 1. Check current settings
ce-ace tune show

# 2. Adjust search for broader matches
ce-ace tune --constitution-threshold 0.35

# 3. Increase max results
ce-ace tune --search-top-k 15

# 4. Enable token budget
ce-ace tune --token-budget-enforcement true --max-playbook-tokens 50000

# 5. Verify changes
ce-ace tune show

# 6. Later, reset to org/server defaults
ce-ace tune --reset
```

## Output Format

### ce-ace tune show

```
🎛️  ACE Configuration

ℹ Project: prj_d3a244129d62c198
ℹ Organization: org_34fYIlitYk4nyFuTvtsAzA6uUJF

ℹ Search/Retrieval:
ℹ   Constitution Threshold: 0.45 (similarity)
ℹ   Search Top K:           10 (max results)

ℹ Deduplication:
ℹ   Enabled:                true
ℹ   Similarity Threshold:   0.85

ℹ Token Budget:
ℹ   Enforcement:            false
ℹ   Max Playbook Tokens:    (not set)
ℹ   Pruning Threshold:      0.3

ℹ Batch Processing:
ℹ   Max Batch Size:         50

ℹ Learning Pipeline:
ℹ   Auto Learning:          true
ℹ   Reflector (Sonnet 4):   true
ℹ   Curator (Haiku 4.5):    true
```

### ce-ace tune --constitution-threshold 0.5

```
✅ Configuration updated successfully

🎛️  ACE Configuration

ℹ Project: prj_d3a244129d62c198
ℹ Organization: org_34fYIlitYk4nyFuTvtsAzA6uUJF

ℹ Search/Retrieval:
ℹ   Constitution Threshold: 0.5 (similarity)  ← Updated
ℹ   Search Top K:           10 (max results)
...
```

### ce-ace tune --reset

```
✅ Configuration reset successfully

All project-level overrides removed.
Project now inherits organization and server defaults.

Run 'ce-ace tune show' to see current effective config.
```

## Important Notes

### Project-Scoped Configuration

- All `/ace-tune` changes affect **THIS PROJECT ONLY**
- Changes persist on the server and sync across sessions
- Other projects maintain their own independent configurations
- Organization-level defaults can be set via web dashboard

### Environment Context

The `ce-ace` CLI automatically reads context from:
1. `ACE_ORG_ID` environment variable (passed by slash command)
2. `ACE_PROJECT_ID` environment variable (passed by slash command)
3. `~/.config/ace/config.json` for API token

You don't need to manually specify these - the slash command handles it.

### Multi-Tenant Safety

- Each project maintains independent configuration
- Configuration hierarchy: Project > Organization > Server
- Project overrides take precedence over org defaults
- Organization-wide settings require web dashboard access

## Performance Notes

- Configuration changes are **immediate** (no restart required)
- Changes **persist across sessions** (stored on server)
- Configuration is fetched fresh on each command (no stale cache issues)
- Hierarchical config resolved server-side (project → org → server)
- Average response time: 200-500ms for show, 300-600ms for updates

## See Also

- `/ace-search` - Semantic search (uses `constitution_threshold`)
- `/ace-status` - View playbook statistics
- `/ace-patterns` - View full playbook
- `/ace-top` - Get highest-rated patterns
- `/ace-configure` - Initial project setup

## Web Dashboard

For organization-wide configuration management:
**https://ace-dashboard.code-engine.app/org/{org_id}/settings**

Use the web dashboard to:
- Set organization-wide defaults
- Manage multiple projects
- View organization-level analytics
- Configure team permissions