Comprehensive ACE installation and health diagnostic
Comprehensive diagnostic tool that checks your entire ACE setup, including plugin installation, configurations, CLI availability, server connectivity, and hook registration. Use this when experiencing issues or after installation to verify everything is configured correctly.
/plugin marketplace add ce-dot-net/ce-claude-marketplace/plugin install ace@ce-dot-net-marketplaceComprehensive diagnostic tool that checks your entire ACE setup and identifies issues.
When the user runs /ace:ace-doctor, perform a complete health check of the ACE system.
Run all checks in parallel for speed, then present organized results.
What to Check:
# Verify plugin directory structure
ls -la ~/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace/
Expected Structure:
ace/
āāā commands/ # Slash commands (/ace-search, /ace-patterns, etc.)
āāā hooks/
ā āāā hooks.json # Hook definitions
āāā scripts/ # Hook wrapper scripts
ā āāā ace_install_cli.sh
ā āāā ace_before_task_wrapper.sh
ā āāā ace_task_complete_wrapper.sh
ā āāā ace_after_task_wrapper.sh
āāā plugin.json
āāā CLAUDE.md
Report:
If Failed:
ā Plugin Installation: NOT FOUND
Recommended Actions:
1. Install plugin via Claude Code marketplace
2. OR install via symlink:
ln -s /path/to/ace ~/.claude/plugins/ace
3. Restart Claude Code after installation
What to Check:
# Check global config exists (XDG standard path)
XDG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
CONFIG_PATH="$XDG_HOME/ace/config.json"
test -f "$CONFIG_PATH" && echo "EXISTS" || echo "MISSING"
# If exists, validate JSON and check required fields
jq -e '.serverUrl, .apiToken, .cacheTtlMinutes, .autoUpdateEnabled' "$CONFIG_PATH"
Expected:
{
"serverUrl": "https://ace-api.code-engine.app",
"apiToken": "ace_xxxxx",
"cacheTtlMinutes": 120,
"autoUpdateEnabled": true
}
Report:
If Failed:
ā Global Configuration: MISSING
Recommended Actions:
1. Run: /ace:ace-configure --global
2. Provide:
- Server URL (https://ace-api.code-engine.app)
- API Token (starts with ace_)
If Incomplete:
ā ļø Global Configuration: INCOMPLETE
Missing fields: apiToken, cacheTtlMinutes
Recommended Actions:
1. Run: /ace:ace-configure --global
2. This will preserve existing values and fill missing fields
What to Check:
# Get project root
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
# Check project settings
test -f "$PROJECT_ROOT/.claude/settings.json" && echo "EXISTS" || echo "MISSING"
# If exists, validate ACE_PROJECT_ID env var
jq -e '.projectId' "$PROJECT_ROOT/.claude/settings.json"
Expected:
{
"env": {
"ACE_PROJECT_ID": "prj_xxxxx"
}
}
Report:
Note: ace-cli is used for all ACE operations.
If Failed:
ā Project Configuration: MISSING
Recommended Actions:
1. Run: /ace:ace-configure --project
2. Provide your project ID (starts with prj_)
If Using @latest:
ā ļø Project Configuration: USING @latest
Current: "@ce-dot-net/ace-client@latest"
Recommended: "@ce-dot-net/ace-client@3.7.2"
Issue: @latest causes npx caching - updates won't install automatically
Recommended Actions:
1. Run: /ace:ace-configure --project
2. This will update to pinned version 3.7.0
What to Check:
# Check if ace-cli is installed and working
command -v ace-cli >/dev/null 2>&1 && echo "INSTALLED" || echo "NOT FOUND"
# If installed, check version
ace-cli --version
Report:
If Failed:
ā CLI: NOT FOUND
Possible Causes:
1. ace-cli not installed globally
2. npm global bin path not in PATH
Recommended Actions:
1. Install: npm install -g @ace-sdk/cli
2. Check version: ace-cli --version
3. Verify PATH includes npm global bin: npm bin -g
What to Check:
# Read serverUrl and apiToken from global config
XDG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
SERVER_URL=$(jq -r '.serverUrl' "$XDG_HOME/ace/config.json")
API_TOKEN=$(jq -r '.apiToken' "$XDG_HOME/ace/config.json")
PROJECT_ID=$(jq -r '.projectId' .claude/settings.json)
# Test connection to ACE server
curl -s -X GET \
-H "Authorization: Bearer $API_TOKEN" \
"$SERVER_URL/api/projects/$PROJECT_ID/playbook" \
-w "\nHTTP: %{http_code}\n" \
-o /tmp/ace-doctor-response.json
Report:
If Failed:
ā ACE Server: UNREACHABLE
Server URL: https://ace-api.code-engine.app
HTTP Status: Connection refused
Possible Causes:
1. Network connectivity issues
2. Firewall blocking HTTPS
3. Incorrect server URL
Recommended Actions:
1. Test connection: curl https://ace-api.code-engine.app/api/health
2. Check firewall settings
3. Try different network (WiFi vs. Ethernet)
4. Verify serverUrl in ~/.config/ace/config.json
If 401 Unauthorized:
ā ļø ACE Server: AUTHENTICATION FAILED
Server URL: https://ace-api.code-engine.app
HTTP Status: 401 Unauthorized
Recommended Actions:
1. Verify API token is correct
2. Check token hasn't expired
3. Run: /ace:ace-configure --global
4. Get new token from ACE server admin
If 404 Not Found:
ā ļø ACE Server: PROJECT NOT FOUND
Project ID: prj_xxxxx
HTTP Status: 404 Not Found
Recommended Actions:
1. Verify project ID exists in ACE server
2. Check you have access to this project
3. Run: /ace:ace-configure --project
4. Create new project in ACE dashboard
What to Check:
# Check if hook scripts exist
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace"
# Check hook wrappers in scripts/
test -f "$PLUGIN_ROOT/scripts/ace_before_task_wrapper.sh" && echo "before_task: EXISTS"
test -f "$PLUGIN_ROOT/scripts/ace_task_complete_wrapper.sh" && echo "task_complete: EXISTS"
test -f "$PLUGIN_ROOT/scripts/ace_after_task_wrapper.sh" && echo "after_task: EXISTS"
test -f "$PLUGIN_ROOT/scripts/ace_install_cli.sh" && echo "install_cli: EXISTS"
# Check hooks.json
test -f "$PLUGIN_ROOT/hooks/hooks.json" && echo "hooks.json: EXISTS"
Expected Hooks (5 total):
SessionStart ā ace_install_cli.shUserPromptSubmit ā ace_before_task_wrapper.shPostToolUse ā ace_task_complete_wrapper.shPreCompact ā ace_after_task_wrapper.shStop ā ace_after_task_wrapper.shReport:
If Failed:
ā Hooks: NOT REGISTERED
Expected Hook Scripts:
- ace_before_task_wrapper.sh (retrieves patterns before tasks)
- ace_task_complete_wrapper.sh (captures learning after tasks)
- ace_after_task_wrapper.sh (backup learning at session end)
- ace_install_cli.sh (ensures ace-cli is available)
Recommended Actions:
1. Verify plugin installation (Check 1)
2. Check scripts/ directory exists in plugin
3. Verify hooks.json exists in hooks/ directory
4. Run: /ace:ace-test to verify hook execution
5. Check Claude Code logs for hook errors
What to Check:
# Check if CLAUDE.md exists in project root
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
test -f "$PROJECT_ROOT/CLAUDE.md" && echo "EXISTS" || echo "MISSING"
# If exists, check for ACE section
grep -q "ACE_SECTION_START" "$PROJECT_ROOT/CLAUDE.md" && echo "HAS_ACE" || echo "NO_ACE"
# Extract version
grep -oP 'ACE_SECTION_START v\K[\d.]+' "$PROJECT_ROOT/CLAUDE.md"
Report:
If Missing:
ā CLAUDE.md: NOT FOUND
Recommended Actions:
1. Run: /ace:ace-claude-init
2. This will create CLAUDE.md with ACE instructions
3. Documents hook-based architecture and automatic learning
4. Commit CLAUDE.md to your repository
If Outdated:
ā ļø CLAUDE.md: OUTDATED VERSION
Current: v4.x.x (or earlier)
Latest: v5.1.2
Breaking Change: v5.x uses hooks instead of skills/subagents
Recommended Actions:
1. Run: /ace:ace-claude-init
2. This will update to hook-based architecture
3. Review CHANGELOG.md for migration details
What to Check:
# Check ace-cli config
XDG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
test -f "$XDG_HOME/ace/config.json" && echo "CONFIG: EXISTS"
# Check if multi-org format (ace-cli v1.x)
jq -e '.organizations' "$XDG_HOME/ace/config.json" >/dev/null 2>&1 && echo "FORMAT: MULTI-ORG"
# Check required fields
jq -e '.organizations[0].apiKey' "$XDG_HOME/ace/config.json" >/dev/null 2>&1 && echo "API_KEY: SET"
Expected (ace-cli v1.x multi-org format):
{
"organizations": [
{
"name": "ce-dot-net",
"apiKey": "ace_xxxxx"
}
],
"activeOrg": "ce-dot-net"
}
Report:
If Old Format:
ā ļø CLI Configuration: OLD FORMAT
Current: Single-org format (ace-cli v0.x)
Expected: Multi-org format (ace-cli v1.x+)
Recommended Actions:
1. Update ace-cli: npm install -g @ace-sdk/cli@latest
2. Run: ace-cli configure
3. Or run: /ace:ace-configure
What to Check:
# Get plugin version
PLUGIN_JSON="$HOME/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace/plugin.json"
if [ -f "$PLUGIN_JSON" ]; then
jq -r '.version' "$PLUGIN_JSON"
else
echo "unknown"
fi
# Get ace-cli version
if command -v ace-cli >/dev/null 2>&1; then
ace-cli --version 2>/dev/null || echo "unknown"
else
echo "not installed"
fi
# Check for Python hooks (shared-hooks/)
if [ -d "shared-hooks" ]; then
echo "Python hooks: present"
else
echo "Python hooks: missing (required for v5.x)"
fi
Expected Versions (as of 2024-11):
Report:
If Updates Available:
ā ļø Updates Recommended
Plugin: v5.1.1 ā v5.1.2 (latest)
ace-cli: v1.0.8 ā v1.0.9 (latest)
Changes in v5.1.2:
- Context passing bug fix (subprocess environment variables)
- Improved error handling in Python hooks
Recommended Actions:
1. Update ace-cli: npm install -g @ace-sdk/cli@latest
2. Update plugin from marketplace (if available)
3. Run: /ace:ace-claude-init to update CLAUDE.md
4. Restart Claude Code
After running all checks, present results in this format:
𩺠ACE Doctor - Health Diagnostic Report
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
[1] Plugin Installation................... ā
PASS
[2] Global Configuration................. ā
PASS
[3] Project Configuration................ ā
PASS
[4] CLI Availability..................... ā
PASS (v1.0.9)
[5] ACE Server Connectivity.............. ā
PASS (HTTP 200)
[6] Hooks Registered..................... ā
PASS (5/5)
[7] CLAUDE.md Status..................... ā
PASS (v5.1.2)
[8] CLI Configuration.................... ā
PASS (multi-org)
[9] Version Status....................... ā
PASS
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Overall Health: š¢ HEALTHY
ā
All systems operational!
ACE is properly configured and ready to use.
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
System Information:
Plugin Version: v5.1.2
CLI Version: v1.0.9
Architecture: Hook-based (v5.x)
Project ID: prj_d3a244129d62c198
Organization: org_34fYIlitYk4nyFuTvtsAzA6uUJF
Registered Hooks:
⢠SessionStart ā ace_install_cli.sh
⢠UserPromptSubmit ā ace_before_task_wrapper.sh
⢠PostToolUse ā ace_task_complete_wrapper.sh
⢠PreCompact ā ace_after_task_wrapper.sh
⢠Stop ā ace_after_task_wrapper.sh
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
For detailed troubleshooting, see:
- README.md (section: š Troubleshooting)
- /ace:ace-test (hook execution test)
Report issues: https://github.com/ce-dot-net/ce-claude-marketplace/issues
𩺠ACE Doctor - Health Diagnostic Report
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
[1] Plugin Installation................... ā
PASS
[2] Global Configuration................. ā
PASS
[3] Project Configuration................ ā ļø WARN
[4] CLI Availability..................... ā
PASS (v1.0.9)
[5] ACE Server Connectivity.............. ā
PASS (HTTP 200)
[6] Hooks Registered..................... ā ļø WARN (3/5)
[7] CLAUDE.md Status..................... ā ļø WARN (v4.2.0)
[8] CLI Configuration.................... ā
PASS
[9] Version Status....................... ā ļø WARN
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Overall Health: š” NEEDS ATTENTION (4 warnings)
ā ļø Warnings Found:
[3] Project Configuration
Issue: projectId missing in .claude/settings.json
Impact: Hooks cannot determine which project to use
Fix: Run /ace:ace-configure
[6] Hooks Registered
Issue: Some hook scripts missing (3/5 found)
Missing: ace_task_complete_wrapper.sh, ace_after_task_wrapper.sh
Impact: Learning capture won't work after tasks
Fix: Reinstall plugin or check scripts/ directory
[7] CLAUDE.md Status
Issue: Outdated version (v4.2.0, latest: v5.1.2)
Impact: Using old skills-based architecture instead of hooks
Fix: Run /ace:ace-claude-init
[9] Version Status
Issue: Updates available
Plugin: v5.1.1 ā v5.1.2
CLI: v1.0.8 ā v1.0.9
Fix: See recommended actions below
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
šÆ Quick Fix All Issues:
Run these commands in order:
1. /ace:ace-configure
2. /ace:ace-claude-init
3. npm install -g @ace-sdk/cli@latest
4. Restart Claude Code
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
System Information:
Plugin Version: v5.1.1
CLI Version: v1.0.8
Architecture: Hook-based (v5.x)
Project ID: (not configured)
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
For detailed troubleshooting, see:
- README.md (section: š Troubleshooting)
- /ace:ace-test (hook execution test)
Report issues: https://github.com/ce-dot-net/ce-claude-marketplace/issues
Use these status indicators:
Run all checks in parallel for speed (< 5 seconds total).
Use Promise.all() or concurrent bash commands where possible.
If any check throws an error:
This is a diagnostic command - NEVER exit with error code. Always complete all checks and present full report.
/ace:ace-test - Plugin-specific tests/ace:ace-status - Playbook statistics/ace:ace-configure - Configuration wizard