CC Agents
Relevant source files
The following files were used as context for generating this wiki page:
CC Agents (Claude Code Agents) are specialized, autonomous AI entities within the opcode ecosystem designed to automate complex software development workflows. By leveraging custom system prompts, specialized sub-agent spawning, and background process execution, these agents perform targeted tasks such as security auditing, unit test generation, and Git workflow automation.
Sources: cc_agents/README.md:1-15, src/components/CCAgents.tsx:40-45
1. System Architecture
The CC Agent system follows a multi-tier architecture involving a React frontend for management, a Rust/Tauri backend for process orchestration and persistence, and a SQLite database for state management.
1.1 Data Model
Agents are stored as structured entities that define their behavior, model preferences, and security permissions.
| Field | Type | Description |
|---|---|---|
name | TEXT | The display name of the agent. |
icon | TEXT | Identifier for the UI icon (e.g., bot, shield, code). |
system_prompt | TEXT | The primary instructions defining the agent's logic and role. |
default_task | TEXT | Optional pre-configured task description. |
model | TEXT | The Claude model family to use (sonnet or opus). |
hooks | TEXT | JSON string of HooksConfiguration for lifecycle events. |
Sources: src-tauri/src/commands/agents.rs:25-40, src/lib/api.ts:117-130
1.2 Agent Discovery and Sources
The system aggregates agents from two primary sources:
- Database: User-created agents stored in the local SQLite database.
- Filesystem: Markdown files with YAML frontmatter located in
~/.claude/agents/. - GitHub: Pre-built community agents available for import via the official repository.
Sources: src-tauri/src/commands/agents.rs:356-365, cc_agents/README.md:32-45
2. Agent Execution Lifecycle
When an agent is executed, the backend spawns a non-blocking background process to run the claude CLI with specific system prompts and task instructions.
2.1 Process Flow
The execution flow involves initializing database records, spawning the system process, and streaming JSONL output back to the UI.
This diagram illustrates the lifecycle of a CC Agent from the initial user trigger to completion.
Sources: src-tauri/src/commands/agents.rs:595-650, src/components/AgentExecution.tsx:162-210
2.2 Output Management
The system captures both real-time stdout from the process and historical data from the .jsonl session files stored in ~/.claude/projects/. This allows for both live monitoring and post-execution metrics analysis.
Sources: src-tauri/src/commands/agents.rs:114-130, src/components/AgentExecution.tsx:235-255
3. Specialized Agent Implementations
Standard agents use advanced prompting techniques like <task_spawn> to orchestrate multiple phases of work.
3.1 Security Scanner Agent
The Security Scanner implements a Static Application Security Testing (SAST) workflow. It operates through six distinct phases:
- Intelligence Gathering: Extracts language, framework, and architecture patterns.
- Threat Modeling: Performs STRIDE analysis and trust boundary identification.
- Vulnerability Scanning: Checks against OWASP Top 10 and CWE categories.
- Exploit Validation: Develops proof-of-concept (PoC) exploits to confirm findings.
- Remediation Design: Architecting immediate patches and long-term defenses.
- Report Generation: Compiling findings into professional security reports.
Sources: cc_agents/security-scanner.opcode.json:11-120
3.2 Unit Test Bot
This agent focuses on codebase coverage and style consistency. It utilizes sub-agents for specific phases:
- Codebase Analyzer: Determines existing test frameworks and conventions.
- Test Writer: Generates code matching local naming and assertion styles.
- Coverage Optimizer: Targets uncovered branches and critical paths (targeting >80% coverage).
Sources: cc_agents/unit-tests-bot.opcode.json:13-75
4. Technical Implementation Details
4.1 Persistance Layer (Rust)
The backend uses rusqlite to manage the agent_runs table, which tracks the history and status of every agent execution.
// From src-tauri/src/commands/agents.rs
conn.execute(
"CREATE TABLE IF NOT EXISTS agent_runs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
agent_id INTEGER NOT NULL,
agent_name TEXT NOT NULL,
task TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending',
pid INTEGER,
created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
completed_at TEXT
)",
[],
)?;
Sources: src-tauri/src/commands/agents.rs:188-205
4.2 Frontend Management (React)
The CCAgents.tsx component provides a grid-based interface for managing the agent library. Key functionalities include:
- Import/Export: Serializes agents to
.opcode.jsonfiles for sharing. - Pagination: Displays agents in a 3x3 grid (9 per page).
- GitHub Browser: Integrated browser for fetching agents directly from the community repository.
Sources: src/components/CCAgents.tsx:68-120, src/components/GitHubAgentBrowser.tsx:100-150
5. Summary
CC Agents represent the automation core of opcode. By providing a bridge between the Claude Code CLI and a structured management interface, the system allows developers to deploy specialized "AI bots" for repetitive or complex software engineering tasks. The architecture ensures that these agents run in isolated background processes while maintaining full visibility via real-time streaming and local execution history.
Sources: cc_agents/README.md:105-120, src/components/AgentExecution.tsx:645-660