bruno/luzia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ec33ac1936cdb66a19af5380ced04c3856b04dc5
luzia/docs/LUZIA_COMMAND_REFERENCE.md
admin ec33ac1936 Refactor cockpit to use DockerTmuxController pattern 
Based on claude-code-tools TmuxCLIController, this refactor:

- Added DockerTmuxController class for robust tmux session management
- Implements send_keys() with configurable delay_enter
- Implements capture_pane() for output retrieval
- Implements wait_for_prompt() for pattern-based completion detection
- Implements wait_for_idle() for content-hash-based idle detection
- Implements wait_for_shell_prompt() for shell prompt detection

Also includes workflow improvements:
- Pre-task git snapshot before agent execution
- Post-task commit protocol in agent guidelines

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-14 10:42:16 -03:00

8.2 KiB
Raw Blame History

Luzia Command Reference

Luzia is the unified access point for managing all tasks and projects in the server agents infrastructure.

Quick Start

luzia --help                    # Show all commands
luzia list                      # List all available projects
luzia status                    # Show current system status
luzia <project> <task>          # Run a task in a project

Core Commands

Project Execution

Command Description
luzia <project> <task> Execute a task in a project's Docker container
luzia work on <project> Start interactive session for a project (delegates to subagent)
luzia list List all available projects with their status
luzia status [project] Show overall status or specific project status
luzia stop <project> Stop a running container
luzia history <project> View recent changes in a project

Examples:

luzia musica analyze logs
luzia work on overbits
luzia list
luzia status dss

Maintenance & System Commands

Cleanup Operations

Command Description
luzia cleanup Full maintenance (jobs + containers + logs)
luzia cleanup jobs Clean old job directories only
luzia cleanup containers Stop stale containers only
luzia cleanup --dry-run Preview cleanup without deleting

Examples:

luzia cleanup --dry-run
luzia cleanup containers
luzia cleanup jobs

System Status

Command Description
luzia maintenance Show maintenance status and recommendations
luzia jobs [job_id] List all jobs or show details for a specific job
luzia logs [project] View project execution logs

Examples:

luzia maintenance
luzia jobs
luzia jobs abc123def
luzia logs dss

Job Management

Failure Management (Smart Retry)

Command Description
luzia failures List recent failures with exit codes
luzia failures <job_id> Show detailed failure information
luzia failures --summary Summary breakdown by exit code
luzia failures --auto-retry Auto-retry all fixable failures
luzia retry <job_id> Retry a specific failed job
luzia kill <job_id> Kill a running agent job

Examples:

luzia failures
luzia failures abc123def
luzia failures --summary
luzia failures --auto-retry
luzia retry abc123def
luzia kill abc123def

Knowledge Graph & Documentation

QA & Validation

Command Description
luzia qa Run QA validation checks
luzia qa --sync Sync code to knowledge graph

Examples:

luzia qa
luzia qa --sync

Documentation Search

Command Description
luzia docs <query> Search all knowledge graphs
luzia docs sysadmin <query> Search sysadmin domain
luzia docs --show <entity> Show entity details from KG
luzia docs --stats Show knowledge graph statistics
luzia docs --sync Sync .md files to knowledge graph

Examples:

luzia docs docker setup
luzia docs sysadmin nginx
luzia docs --show nginx
luzia docs --stats
luzia docs --sync

Research & Analysis

Research Commands (3-Phase Flow)

Command Description
luzia research [project] <topic> Start research (context → search → synthesize)
luzia deep research [project] <topic> Same as research (alias)
luzia web research [project] <topic> Same as research (alias)
luzia research-list [project] List research sessions
luzia research-show <session_id> Show research session details
luzia research-knowledge [project] Show project knowledge graph

Examples:

luzia research musica database optimization
luzia deep research dss performance tuning
luzia web research overbits authentication
luzia research-list dss
luzia research-show sess_abc123
luzia research-knowledge musica

Internal Research Operations (Called During Flow)

Command Description
luzia research-update <id> <phase> <json> Update research phase (internal)
luzia research-graph <id> <json> Add entities to knowledge graph (internal)

Code Analysis & Intelligence

Structural Analysis

Command Description
luzia structure Analyze current orchestrator structure
luzia structure <project> Analyze a specific project
luzia structure . path/src Analyze specific subdirectory
luzia structure --json Output analysis as JSON
luzia structure --no-kg Don't save to knowledge graph

Examples:

luzia structure
luzia structure dss
luzia structure . lib/docker_bridge.py
luzia structure --json > analysis.json
luzia structure --no-kg

Advanced Features

Deep Reasoning

Command Description
luzia think deep <topic> Deep reasoning via Zen + Gemini 3

Examples:

luzia think deep "how to optimize docker image size"

Troubleshooting

Command Description
luzia fix <issue> Troubleshooting assistant

Examples:

luzia fix "container not starting"

Notifications

Command Description
luzia notify View notifications
luzia notifications Alias for notify

Queue Management (Advanced)

Command Description
luzia queue Show queue status
luzia dispatch <job> Dispatch a job to the queue

Examples:

luzia queue
luzia dispatch research_agent

Low-Level Operations

These are primarily for internal use:

Command Description
luzia --exec <project> <command> Execute raw command (JSON output)
luzia --read <project> <path> Read file contents (JSON output)
luzia --write <project> <path> <content> Write to file (JSON output)
luzia --context <project> Get project context (JSON output)

Examples:

luzia --exec musica ls -la
luzia --read dss /workspace/config.json
luzia --write overbits /workspace/test.txt "content here"
luzia --context librechat

Global Flags

Flag Description
--help, -h, help Show this help message
--verbose Enable verbose output
--fg Run in foreground (don't background)

Examples:

luzia --help
luzia --verbose status
luzia --fg musica analyze data

Exit Codes

Code Meaning
0 Success
1 General error
2 Invalid arguments
3 Project not found
4 Container error

Common Patterns

Check System Health

luzia list          # See all projects
luzia status        # Overall status
luzia maintenance   # System recommendations

Run a Task

luzia <project> <task> <args>

Manage Failures

luzia failures              # See what failed
luzia failures --summary    # Breakdown by code
luzia retry <job_id>        # Retry one
luzia failures --auto-retry # Retry all fixable

Research a Topic

luzia research musica "how to optimize queries"
luzia research-show <session_id>
luzia research-knowledge musica

Analyze Code

luzia structure dss --json
luzia docs dss "query"
luzia qa --sync

Configuration

Configuration is loaded from /opt/server-agents/orchestrator/config.json:

{
  "projects": {
    "musica": {
      "image": "musica:latest",
      "port": 3000
    },
    ...
  }
}

Troubleshooting

"Unknown: "

The command wasn't recognized. Use luzia --help to see valid commands.

"Permission denied"

You may not have permission to run commands in that project. Check your user permissions.

Container errors

Run luzia cleanup containers to stop stale containers, then try again.

Job failures

Use luzia failures to see what went wrong, then luzia retry <job_id>.

See Also

  • /opt/server-agents/orchestrator/docs/ - Full documentation
  • /opt/server-agents/CLAUDE.md - Project instructions
  • /etc/claude/GLOBAL.md - Global server rules
Reference in New Issue View Git Blame Copy Permalink