sudocode

🥈Silver

sudocode is a lightweight agent orchestration tool that lives in your repo. It enables operations teams to automate workflows using AI agents. Connects to CLI and supports multi-agent workflows.

272130Updated 2mo ago

Intermediate30min to implementautomation

Saves ~240 min per use

Quick InstallView Source

git clone https://github.com/sudocode-ai/sudocode.git

Works with:

Claude

Overview

About This Skill

sudocode is a lightweight agent orchestration tool that lives in your repo. It enables operations teams to automate workflows using AI agents. Connects to CLI and supports multi-agent workflows.

How to Use

1. **Install sudocode**: Run `pip install sudocode` in your project repo. Verify installation with `sudocode --version`. 2. **Define Agents**: Create a `.sudocode/agents/` directory and add YAML files for each agent (e.g., `file_validator.yaml`, `test_runner.yaml`). Use the example output as a template for agent definitions. 3. **Configure Workflow**: In `.sudocode/workflows/`, define a YAML file (e.g., `pr-validation-pipeline.yaml`) with the agent roles, handoff logic, and error handling. Validate the syntax with `sudocode validate --workflow pr-validation-pipeline`. 4. **Test Locally**: Run the workflow in dry-run mode first: `sudocode run --workflow pr-validation-pipeline --dry-run`. Check logs in `.sudocode/logs/` for debugging. 5. **Integrate with CI/CD**: Add the workflow to your GitHub Actions or GitLab CI pipeline. Example: ```yaml # .github/workflows/sudocode.yml - name: Run sudocode workflow run: sudocode run --workflow pr-validation-pipeline ``` **Tips:** - Use `sudocode logs --tail` to monitor real-time execution. - For complex workflows, break agents into smaller, reusable components (e.g., a `notifier` agent shared across workflows). - Store sensitive data (e.g., API keys) in `.sudocode/secrets/` and reference them in agent configs as `${secrets.SLACK_WEBHOOK}`.

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/sudocode-ai/sudocode

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Use sudocode to automate the following workflow in [REPO_PATH]: [WORKFLOW_DESCRIPTION]. Define the agents required (e.g., 'a file validator agent, a test runner agent, and a deployment agent'), specify their roles, and outline the handoff logic between them. Include error handling for [COMMON_FAILURE_CASES].

Example Output

### Sudocode Workflow Definition for CI/CD Pipeline

**Workflow Name:** `pr-validation-pipeline`
**Repo Path:** `/projects/web-app`

#### Agents:
1. **FileValidatorAgent**
   - **Role:** Validates changed files against `.sudocode/rules/pr-rules.yaml` (e.g., no direct pushes to `main`, no large binary files).
   - **Input:** Git diff from `origin/main..HEAD`.
   - **Output:** `validation_report.json` with `status` (PASS/FAIL) and `violations` (array).
   - **Error Handling:** If validation fails, trigger `SlackNotifierAgent` with violation details.

2. **TestRunnerAgent**
   - **Role:** Runs unit/integration tests in `/tests/` using `pytest`.
   - **Input:** Validation report (if PASS).
   - **Output:** `test_results.json` with `coverage` (%), `passed_tests` (count), and `failed_tests` (array of test names).
   - **Error Handling:** If tests fail, trigger `RollbackAgent` to revert last commit and notify the team via `SlackNotifierAgent`.

3. **DeploymentAgent**
   - **Role:** Deploys to staging if tests pass. Uses `docker build` and `kubectl apply`.
   - **Input:** Test results (if PASS).
   - **Output:** `deployment_status.json` with `status` (SUCCESS/FAIL) and `logs` (array).
   - **Error Handling:** If deployment fails, trigger `RollbackAgent` and log the error to `Sentry`.

4. **RollbackAgent** (Fallback)
   - **Role:** Reverts the last commit and rolls back the deployment.
   - **Input:** Failure trigger from any agent.
   - **Output:** `rollback_status.json` with `status` (SUCCESS/FAIL).

#### Handoff Logic:
```yaml
workflow:
  steps:
    - agent: FileValidatorAgent
      next: [TestRunnerAgent, SlackNotifierAgent]  # Parallel paths
    - agent: TestRunnerAgent
      next: [DeploymentAgent, RollbackAgent]        # Conditional path
    - agent: DeploymentAgent
      next: []                                      # Terminal
    - agent: RollbackAgent
      next: []                                      # Terminal
  on_failure: SlackNotifierAgent
```

#### CLI Integration:
```bash
# Trigger the workflow
sudocode run --workflow pr-validation-pipeline --repo /projects/web-app

# Monitor progress
sudocode status --workflow pr-validation-pipeline
```

**Expected Output:**
The workflow would execute in ~2 minutes. If all agents succeed, the deployment status would show:
```json
{
  "deployment_status": {
    "status": "SUCCESS",
    "environment": "staging",
    "logs": ["Build completed in 45s", "Deployed to staging-v2.1"]
  }
}
```