CodeCargo Agent Spec

CodeCargo agents can be defined as files in git, so the definition is reviewed, versioned, and diffed like any other code. This page is the reference for that file format. For how agents are governed once they reach the catalog, see Agent Catalog.

File Location

Agent definitions live at:

.codecargo/agents/<name>.agent.md

• Files must sit directly in .codecargo/agents/ — subdirectories are not scanned.
• The double extension .agent.md is required (case-insensitive). Other files in the directory, such as a README.md, are ignored.
• Only the repository's default branch is scanned.

The .codecargo/ directory is deliberately inert to GitHub — unlike .github/workflows/, placing a file here never creates a live Actions workflow. It only describes an agent for CodeCargo to run.

Anatomy

An agent file is YAML frontmatter followed by a markdown body. The body is the agent's prompt — the instructions it reads on every run:

---
name: My Agent
tools:
  - github_read
---

You are an agent that...

Every frontmatter field is optional. A file with no frontmatter at all is a valid, minimal agent: the whole file becomes the prompt, and the agent requests no tools.

Frontmatter Reference

tools

The tools: list is a request, never a grant. An Org Admin reviews the definition and grants an equal or narrower set before the agent can run — see Publishing and Tool Grants. Valid tool tokens:

shell, edit_files, github_read, open_pull_request, create_issue, query_logs, spawn_agents, web_search, read_building_blocks, read_guardrail_findings, read_guardrail_scores, read_repositories, read_workflows, read_services, read_projects

Tokens are matched case-insensitively, ignoring -/_ differences. Unrecognized tokens are dropped from the stored request (the file keeps them for a reviewer to see) rather than failing the file.

tools_requiring_approval

Tools listed here may still be granted, but each run pauses the first time the agent tries to use one and waits for a human decision — see Agentic Jobs → Tool Approvals. Approval requirements expand across tool implications (for example, a gate on edit_files cannot be routed around via shell), and a repository scan can add gates the file requests but never remove one a reviewer imposed.

mcp-servers

Requests access to MCP servers from your organization's catalog, by name (a file in git can't know org-internal server IDs). Three equivalent shapes:

mcp-servers: [jira, github]          # names only — request all capped tools

mcp-servers:
  - name: jira
    tools: [search, create_issue]    # request a subset of the server's tools

mcp-servers:
  jira:
    tools: [search]                  # mapping keyed by server name

Names resolve case-insensitively against the catalog. A name that doesn't match any approved server isn't dropped — it's kept and surfaced in review as a server the organization hasn't approved. The tools requested are bounded by both the admin's grant and the server's own tool cap in the MCP catalog.

inputs

Declares run-time parameters. Each input has a name (also accepted: id, key), a type (string, number, or bool, with common aliases like text, int, boolean; default string), and optionally required, description, default, and — for strings — an options list (choices and enum also accepted). Option entries may be bare values or { value, label } pairs.

inputs:
  - name: target
    type: string
    required: true
    description: The dependency or group to upgrade.
    options:
      - value: lodash
      - value: react
        label: React
  - name: verbose
    type: bool
    default: false

A mapping form is also accepted, keyed by input name; a bare key declares an optional string input.

repos

Documents what the agent expects of any binding that runs it — not concrete repositories:

repos:
  count: 1 # 0 means any number
  access: write # read | write

Input Placeholders

The prompt body may reference inputs as {{ name }}, where the key is the bare input name (letters, digits, and underscores, starting with a letter or underscore — {{ inputs.target }}-style dotted keys are not substituted). At launch, every declared input is substituted — unset optional inputs become empty strings, booleans render as true/false. A placeholder with no matching input is left as literal text.

Runs fired by an External Event webhook additionally receive the raw JSON payload appended to the prompt as an ## Incoming event block.

Complete Example

---
name: Dependency Upgrader
description: 'Upgrades a dependency group: safely, with a changelog'
model: claude-opus-4-8
tools:
  - github_read
  - edit_files
  - shell
tools_requiring_approval:
  - shell
mcp-servers:
  - name: jira
    tools:
      - search
      - create_issue
inputs:
  - name: target
    type: string
    required: true
    description: The dependency or group to upgrade.
repos:
  count: 1
  access: write
---

You are a dependency-upgrade agent.

Update {{ target }} and open a PR.

Parsing and Validation

Parsing is deliberately tolerant: one malformed file never fails a repository or organization sync, and no file is ever silently dropped.

• Malformed YAML frontmatter — the file is still cataloged, marked unparsed, with its name falling back to the filename stem. An unparsed agent is visible for review but can never run.
• Invalid inputs entry (unknown type, default of the wrong type, unreadable options) — the whole file is flagged unparsed, because a silently dropped input would leave an unsubstituted placeholder in a prompt that still runs.
• Invalid mcp-servers entry, bad repos.count, unknown tool token, or unknown engine — dropped or defaulted per field; the file stays parsed.

Sync and Versioning

The catalog row is a projection; git is the source of truth. Agent files are picked up by the organization workflow sync, and default-branch pushes touching .codecargo/agents/ trigger a targeted re-scan.

• A new file enters the catalog as Needs review with no grants.
• Each revision is identified by a digest of the whole file, so a prompt-only edit counts as a change. A change to a Published agent flips it to Changed: needs re-approval — the previously reviewed revision keeps running for pinned bindings until an admin re-grants.
• A file that disappears from the default branch retires the agent (soft — never deleted; pinned bindings keep resolving from history). If the file returns, the agent is resurrected as Needs review with its grants wiped — unless an admin retired it explicitly, which sticks.

Bindings can pin an agent to a specific commit or float on the default branch head. Floating is not allowed for agents holding sensitive tools (shell, edit_files, create_issue, open_pull_request) — those must pin, so the reviewed definition cannot change underneath the grant.