TeamCast

CLI to design, generate, and validate multi-target agent teams for Claude Code and Codex from a single manifest.

Define your agent team in one teamcast.yaml file. TeamCast validates the manifest, generates .claude/ and/or .codex/ config files, and keeps generated output in sync with the source config.

Install

Requires Node.js 24 or newer.

npm install -g teamcast

Or run without installing:

npx teamcast <command>

Community

• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Bug reports and feature requests: use the GitHub issue templates
• Pull requests: use the repository PR template and run npm test plus npm run build before opening one

Quick Start

# Initialize a new team with the interactive wizard
teamcast init

# Or skip the wizard and use a preset directly
teamcast init --preset feature-team --target both

# Generate files for the targets defined in teamcast.yaml
teamcast generate

# Validate the manifest
teamcast validate

After generate, your project will have files for the selected target(s):

• Claude target:
  • .claude/agents/<name>.md - one file per agent
  • .claude/skills/<skill>/SKILL.md - one stub file per unique skill
  • .claude/settings.json - permissions and sandbox config
  • .claude/settings.local.json - local Claude settings when enabled
  • CLAUDE.md - team documentation for Claude Code
• Codex target:
  • .codex/config.toml - workspace-level Codex config
  • .codex/agents/<name>.toml - one TOML config per agent
  • .agents/skills/<skill>/SKILL.md - one stub file per unique skill
  • AGENTS.md - team-level instructions for Codex agents

Use teamcast init --target claude|codex|both to choose which outputs are generated up front.

Target Model

TeamCast now uses a canonical manifest shape with target-specific blocks:

• claude.agents.<name> - native Claude Code runtime fields and doc outputs
• codex.agents.<name> - native Codex runtime fields and TOML outputs
• <target>.agents.<name>.forge - TeamCast-only metadata such as delegation graph
• project.environments - active project environments (node, python, go, rust, java, ruby, docker, terraform) — auto-detected or explicit

TeamCast includes a built-in registry of capabilities, traits, instruction fragments, policy fragments, models, and skills. These are not serialized into teamcast.yaml.

Legacy flat manifests are still accepted and normalized automatically, but new writes use the canonical shape.

Command Summary

Command	Description
init	Initialize teamcast.yaml and generate files
generate	Generate target files from teamcast.yaml
validate	Validate the team configuration
validate --format json	Machine-readable validation output for CI pipelines
explain	Print a human-readable view of the team architecture
diff	Show what generated files would change
add agent <name>	Add a new agent
edit agent <name>	Edit an existing agent
remove agent <name>	Remove an agent and clean up handoffs
create skill <name>	Create a new skill and assign it to one agent
assign skill <name>	Assign an existing skill to more agents
import	Import an existing .claude/ setup into teamcast.yaml
reset	Delete generated files, keep teamcast.yaml
clean	Delete generated files and teamcast.yaml

Useful options:

teamcast init --preset <name>   # skip wizard and use a preset
teamcast init --from <path>     # initialize from an existing YAML file
teamcast init --target <name>   # generate claude, codex, or both
teamcast init --yes             # non-interactive init, uses defaults
teamcast generate --dry-run     # preview generated files without writing
teamcast validate --strict      # fail on warnings as well as errors
teamcast validate --format json # JSON output, useful in CI scripts
teamcast import --yes           # skip import confirmation
teamcast reset --yes            # skip reset confirmation
teamcast clean --yes            # skip clean confirmation

Presets

Preset	Agents	Workflow
feature-team	orchestrator, planner, developer, reviewer	orchestrator triages and delegates; planner reads code and produces step-by-step plans; developer implements with tests; reviewer checks quality
solo-dev	developer	single full-stack agent handles end-to-end: plan, implement, test, verify
research-and-build	orchestrator, researcher, planner, developer	research-first: orchestrator routes to researcher for external info, planner integrates findings, developer implements
secure-dev	orchestrator, planner, developer, security-auditor, reviewer	mandatory security pipeline: planner includes threat model, developer follows OWASP, security-auditor gates every change, reviewer checks quality
red-blue	orchestrator, red-agent, blue-agent, judge	adversarial hardening: red attacks with failing tests, blue fixes without weakening them, judge decides SHIP or next round

The built-in preset files live in templates/presets/ and are valid TeamCast YAML. Use them as a reference when creating custom presets, or copy one as a starting point:

cp node_modules/teamcast/templates/presets/feature-team.yaml ./my-team.yaml
teamcast init --from ./my-team.yaml

Flows

init

teamcast init creates a fresh teamcast.yaml, validates it, and generates all output files.

Interactive wizard flow:

1. Project name:
   • default is auto-detected from the current directory
   • must match lowercase letters, numbers, and hyphens
2. Which target configs should TeamCast generate?
   • Claude
   • Codex
   • Both
3. How do you want to set up your agent team?
   • Use a preset
   • Custom team
   • Single agent
4. If you choose Use a preset:
   • Select a preset:
5. If you choose Custom team:
   • Select roles for your team:
   • available roles: orchestrator, planner, researcher, developer, tester, reviewer, security-auditor
   • if orchestrator is selected with other roles, handoffs are auto-wired to the other selected agents
6. Customize agents before generating?
   • if yes, each agent gets:
   • Model for <agent>:
   • Reasoning effort [codex]: for Codex agents
7. Select project environments:
   • detected environments (e.g. Node.js, Python) are pre-selected
   • environments inject policies and workflow instructions into capable agents
8. Preview:
   • shows the files that will be created
   • asks Generate these files?

Important limitations of the wizard:

• It does not let you rename individual agents.
• It does not ask for custom instruction_blocks or instruction_fragments.
• It does not ask for environment-specific configuration prompts.
• It does not ask for custom claude.skills, forge.handoffs, claude.max_turns, or exact tool lists.
• Those values come from built-in presets or role templates.
• If you want deeper customization, edit teamcast.yaml after init and run teamcast generate.

Non-interactive init flows:

• teamcast init --preset <name>
  • skips the wizard
  • loads the preset
  • uses the selected --target value, or claude if omitted
  • uses the detected directory name as project.name
  • writes teamcast.yaml
  • generates files immediately
• teamcast init --from ./my-team.yaml
  • loads a custom YAML file
  • validates schema and manifest rules
  • writes teamcast.yaml
  • generates files immediately
• teamcast init --yes
  • runs wizard defaults without prompts
  • uses detected project name
  • uses the feature-team preset
  • skips final confirmation

add agent <name>

teamcast add agent <name> adds a new agent to an existing manifest, writes teamcast.yaml, then regenerates all files.

Two modes are supported:

• teamcast add agent <name>
  • creates a custom agent from a short interactive flow
• teamcast add agent <name> --template <role>
  • creates an agent from a built-in role template

Interactive questions for add agent <name>:

1. Agent description (when should Claude delegate to this agent?):
2. Model:
   • sonnet
   • opus
   • haiku
3. Can this agent write/edit files?
4. Can this agent run shell commands?
5. Can this agent access the internet?
6. Can this agent delegate to other agents?

How those answers map into the manifest:

• Every custom agent gets Read, Grep, and Glob.
• If write access is enabled, TeamCast adds Write, Edit, MultiEdit.
• If bash access is enabled, TeamCast adds Bash.
• If internet access is enabled, TeamCast adds WebFetch, WebSearch.
• If delegation is enabled, TeamCast adds Agent.
• For disabled write/bash/web capabilities, the matching tools are written into claude.disallowed_tools.

What add agent does not ask for:

• claude.instructions
• instruction_blocks
• claude.skills
• forge.handoffs
• claude.max_turns
• claude.permission_mode
• claude.mcp_servers
• a fully custom claude.tools / claude.disallowed_tools list

That means a custom agent added this way starts with a minimal prompt. To make it useful, edit teamcast.yaml and add fields such as instruction_blocks, instruction_fragments, skills, and forge.handoffs.

edit agent <name>

teamcast edit agent <name> updates an existing agent, writes teamcast.yaml, then regenerates all files.

Two modes are supported:

• Non-interactive:

teamcast edit agent reviewer --description "Reviews backend changes"
teamcast edit agent reviewer --model opus
teamcast edit agent reviewer --max-turns 40

• Interactive:

teamcast edit agent reviewer

Interactive questions:

1. Description:
2. Model:
   • sonnet
   • opus
   • haiku
   • inherit
3. Max turns (leave empty to keep current):
4. Customize tools?
5. If yes:
   • Select allowed tools:
   • claude.disallowed_tools is computed automatically as the inverse of the selected allow-list

Important limitations:

• edit agent does not edit instruction_blocks, instruction_fragments, skills, forge.handoffs, permission_mode, or mcp_servers.
• If you pass any direct flags such as --description, --model, or --max-turns, the command updates only those fields and skips the interactive tool editor.

remove agent <name>

teamcast remove agent <name> removes an agent from the manifest, removes that agent from any forge.handoffs, deletes the orphaned .claude/agents/<name>.md file, and regenerates the rest.

Interactive flow:

1. Shows the current agent name
2. Asks:
   • Remove agent "<name>"? This will also remove it from any handoffs.

Use --yes to skip confirmation.

create skill <name>

teamcast create skill <name> registers a new skill name on one agent, writes teamcast.yaml, and generates a target-specific stub: .claude/skills/<name>/SKILL.md for Claude or .agents/skills/<name>/SKILL.md for Codex.

Rules and prompts:

• skill names must start with a letter and use lowercase letters, numbers, and hyphens only
• if the skill already exists anywhere in the manifest, the command fails
• existing skill names are shown for context
• then TeamCast asks:
  • Which agent should own this skill?

The generated SKILL.md file is a stub intended for manual editing. TeamCast will not overwrite an existing skill stub on later generate runs.

assign skill <name>

teamcast assign skill <name> adds an existing skill to one or more additional agents, writes teamcast.yaml, and regenerates files.

Interactive flow:

1. Validates that the skill already exists somewhere in the manifest
2. Prints agents that already have the skill
3. Asks:
   • Assign to which agents?

The prompt is a multi-select list and requires at least one target agent.

generate

teamcast generate reads teamcast.yaml, validates it for blocking issues, and writes generated files.

teamcast generate
teamcast generate --dry-run

Behavior:

• generate overwrites generated agent/docs/settings files
• skill stub files under .claude/skills/ and .agents/skills/ are created only if missing
• --dry-run shows what would be generated without writing anything

diff

teamcast diff compares the current manifest to generated files already on disk.

It reports:

• new files
• modified files with added or removed line counts when available
• unchanged files

Use it to preview drift before running teamcast generate.

validate

teamcast validate runs the validator against teamcast.yaml.

teamcast validate
teamcast validate --strict
teamcast validate --format json

Behavior:

• exits non-zero on validation errors
• with --strict, also exits non-zero on warnings
• with --format json, prints a JSON result object instead of human-readable output; useful for CI scripts that need to parse results programmatically

Validation categories include:

• handoff graph correctness
• tool conflicts
• role-based warnings
• security baseline checks

Policy Assertions

Assertions are declarative rules about your team that validate enforces. Define them under policies.assertions:

policies:
  assertions:
    - rule: require_sandbox_with_execute
    - rule: no_unrestricted_execute
    - rule: max_agents
      count: 6
    - rule: deny_skill_for_role
      agent: reviewer
      skill: write_files

Available rules:

Rule	Parameters	Description
require_sandbox_with_execute	—	Any agent with execute skill must have sandbox enabled
no_unrestricted_execute	—	execute skill must have a permission scope (e.g. Bash(npm *))
require_skill	skill	All agents must have the specified skill
deny_skill_for_role	agent, skill	A named agent must not have the specified skill
forbid_skill_combination	skills[]	No single agent may hold all listed skills at once
max_agents	count	Team must not exceed the given number of agents
require_instruction_block	kind	All agents must include an instruction block of the given kind
require_delegation_chain	—	At least one agent must have the delegate skill

The secure-dev preset includes several security assertions by default.

explain

teamcast explain prints a human-readable summary of the team:

• project metadata
• agents
• models
• tools
• handoffs
• skills

Use this after init, import, or larger manifest edits to sanity-check the architecture.

import

teamcast import converts an existing .claude/ setup into teamcast.yaml.

Preconditions:

• .claude/ must exist
• teamcast.yaml must not already exist

Flow:

1. Scans .claude/agents/*.md
2. Scans .claude/settings.json
3. Builds a manifest
4. Prints import warnings, if any
5. Prints discovered agents and policy categories
6. Validates the imported manifest
7. Asks:
   • Write teamcast.yaml with imported configuration?

Use --yes to skip confirmation.

Important note:

• import writes teamcast.yaml
• it does not run generate
• imported instructions are extracted from the agent markdown body text
• legacy TeamCast markdown is still supported, and old generated Skills, Delegation, and Constraints sections are stripped during import

reset

teamcast reset deletes generated output but keeps teamcast.yaml.

It targets:

• .claude/agents
• .claude/skills
• generated Codex skill files under .agents/skills/
• .claude/settings.json
• .claude/settings.local.json
• CLAUDE.md
• .codex/agents
• .codex/config.toml
• AGENTS.md

Flow:

1. Shows the files that will be deleted
2. Asks:
   • Delete these files?

Use --yes to skip confirmation.

clean

teamcast clean is the destructive version of reset.

It deletes:

• everything removed by reset
• teamcast.yaml

Flow:

1. Shows the files that will be deleted
2. Asks:
   • Delete everything including teamcast.yaml?

Use --yes to skip confirmation.

Prompt Generation

Everything is defined in teamcast.yaml at the root of your project.

For Claude targets, TeamCast renders .claude/agents/<name>.md and CLAUDE.md from claude.agents.<name>.

For Codex targets, TeamCast renders .codex/agents/<name>.toml plus .codex/config.toml from codex.agents.<name>, and writes Codex skill docs to .agents/skills/<skill>/.

.codex/config.toml is the workspace-level agent index. Concrete agent runtime config lives in .codex/agents/<name>.toml. Codex skill discovery uses .agents/skills/, not .codex/.

Native Claude Code fields are rendered into frontmatter:

• description
• model
• tools
• disallowedTools
• permissionMode
• maxTurns
• skills
• mcpServers
• background

instruction_blocks and instruction_fragments compose the markdown body for Claude agents and the instruction sections embedded in Codex developer_instructions.

forge metadata is not rendered into the agent markdown. It is used by TeamCast for validation, workflow docs, and delegation modeling.

Codex agent TOML uses these native fields:

• model
• model_reasoning_effort
• sandbox_mode
• developer_instructions

tools, disallowed_tools, skills, and forge.handoffs are encoded as structured sections inside developer_instructions.

Environment Instructions

Project environments inject capability-gated instructions into agent prompts at generation time. Each environment fragment specifies which capabilities an agent must have to receive it:

Fragment	Requires	Example content
node_code_patterns	read_files	ESM imports, TypeScript strict mode, named exports
node_development	write_files	npm install, async/await, error handling patterns
node_testing	execute + write_files	npm test, vitest/jest commands, test conventions

This means a reviewer (read + execute, no write) gets code patterns but NOT testing instructions. A developer (read + write + execute) gets everything. An orchestrator (read + delegate only) gets only code patterns.

Custom agents work the same way — a react-dev with write_files + execute automatically gets the right fragments without any role-name matching.

Built-in environments

Environment	Auto-detected by	Policy allows
node	package.json	npm, npx, node
python	pyproject.toml, requirements.txt, setup.py	pytest, python, uv, poetry
go	go.mod	go build/test/run/vet/mod
rust	Cargo.toml	cargo, rustfmt, clippy
java	pom.xml, build.gradle	mvn, gradle, ./gradlew
ruby	Gemfile	bundle, rake, rspec
docker	Dockerfile, docker-compose.yml	docker, docker compose
terraform	main.tf, terraform.tf	terraform init/plan/validate/fmt

Custom environments

Drop a YAML file into .agentforge/environments/ to add a new environment or override a builtin:

# .agentforge/environments/bun.yaml
id: bun
description: "Bun runtime environment"
detect_files:
  - bun.lockb
policy_rules:
  sandbox:
    enabled: true
  allow:
    - "Bash(bun *)"
instruction_fragments:
  bun_patterns:
    content: |
      This project uses Bun.
      Use `bun install`, `bun run`, and `bun test`.
    requires_capabilities:
      - read_files

Reference it in teamcast.yaml by id:

project:
  environments: [node, bun]

Instruction Layers

Agent prompts are composed from three layers:

Layer	Source	Scope
instruction_blocks	teamcast.yaml or preset	Project-specific behavior, workflow rules
instruction_fragments	Built-in registry	Reusable role patterns (e.g. feature-developer-workflow)
environment instructions	Built-in + custom environments	Toolchain best practices, injected by capability

Presets provide sensible defaults for instruction_blocks and instruction_fragments. For deeper customization, edit teamcast.yaml and run teamcast generate.

Note for add agent:

• add agent <name> --template <role> inherits the role template's blocks and fragments
• add agent <name> without --template starts with a minimal prompt until you edit teamcast.yaml

Configuration

Everything is defined in teamcast.yaml at the root of your project.

Minimal Example

version: "2"
project:
  name: my-project

claude:
  agents:
    developer:
      description: Implements features and fixes bugs
      model: sonnet
      tools: [Read, Write, Edit, Bash, Grep, Glob]
      disallowed_tools: [WebFetch, WebSearch]
      instruction_blocks:
        - kind: behavior
          content: |
            Implement the requested changes.
            Write tests when behavior changes.

Full Example

version: "2"
project:
  name: my-project
  description: TypeScript/Node.js web app

claude:
  agents:
    orchestrator:
      description: Coordinates the team and delegates tasks
      model: opus
      tools: [Read, Grep, Glob, Agent]
      disallowed_tools: [Edit, Write, Bash]
      max_turns: 30
      instruction_blocks:
        - kind: behavior
          content: |
            You are the coordinator for the project.
            Read the request, break it into subtasks, and delegate to the right agents.
            Never modify files yourself.
      forge:
        handoffs: [planner, developer, reviewer]

    planner:
      description: Analyzes codebase and produces implementation plans
      model: sonnet
      tools: [Read, Grep, Glob, WebFetch, WebSearch]
      disallowed_tools: [Edit, Write, Bash]
      instruction_blocks:
        - kind: behavior
          content: |
            Read the codebase and produce a step-by-step implementation plan.
            Never modify files.

    developer:
      description: Implements features based on the plan
      model: sonnet
      tools: [Read, Write, Edit, Bash, Grep, Glob]
      disallowed_tools: [WebFetch, WebSearch]
      skills: [test-first, clean-code]
      instruction_blocks:
        - kind: behavior
          content: |
            Implement the plan, write tests, and verify the result.

    reviewer:
      description: Reviews code for quality and security issues
      model: sonnet
      tools: [Read, Grep, Glob, Bash]
      disallowed_tools: [Edit, Write]
      instruction_blocks:
        - kind: behavior
          content: |
            Review the implementation for correctness, style, and security.
            Do not modify files yourself.

  policies:
    permissions:
      allow:
        - "Bash(npm run *)"
        - "Bash(npm test)"
        - "Bash(git status)"
        - "Bash(git diff *)"
        - "Bash(git commit *)"
      ask:
        - "Bash(git push *)"
      deny:
        - "Bash(rm -rf *)"
        - "Bash(git push --force *)"
        - "Write(.env*)"
    sandbox:
      enabled: true
      auto_allow_bash: true

  settings:
    generate_docs: true
    generate_local_settings: true

Agent Fields

Field	Type	Description
claude.description	string	Required. Shown in the Claude Code subagent picker
claude.model	opus | sonnet | haiku | inherit	Model alias to use
claude.tools	string[]	Native Claude Code tool allow-list
claude.disallowed_tools	string[]	Native Claude Code tool deny-list
claude.skills	string[]	Skill names. Each unique skill generates .claude/skills/<skill>/SKILL.md
codex.skills	string[]	Skill names. Each unique skill generates .agents/skills/<skill>/SKILL.md
claude.max_turns	number	Maximum agentic turns
claude.mcp_servers	object[]	MCP server definitions
claude.permission_mode	default | acceptEdits | bypassPermissions | plan | dontAsk	Claude Code permission mode
capability_traits	string[]	High-level capability profiles that expand to tools + disallowed_tools
instruction_blocks	object[]	Structured instruction blocks rendered into Claude markdown and Codex developer_instructions
instruction_fragments	string[]	Named instruction fragments composed with instruction_blocks
forge.handoffs	string[]	Other agents this agent can delegate to. Requires Agent in claude.tools

Available Claude Code tools:

Read, Write, Edit, MultiEdit, Grep, Glob, Bash, WebFetch, WebSearch, Agent

Abstract Skills

Instead of listing raw tool names, you can specify platform-agnostic skills in claude.tools. TeamCast expands each skill to the appropriate Claude Code tools automatically.

Skill	Expands to
read_files	Read, Grep, Glob
write_files	Write, Edit, MultiEdit
execute	Bash
search	Glob, Grep
web	WebFetch, WebSearch
delegate	Agent
interact	AskUserQuestion, TodoWrite, TodoRead
notebook	NotebookEdit

Example:

developer:
  claude:
    tools: [read_files, write_files, execute]

Raw tool names and skills can be mixed in the same tools array.

Capability Traits

Capability traits are high-level profiles that compose tools and disallowed_tools from named capability sets. They are the recommended way to define agent permissions in presets and custom manifests — more readable than raw tool lists and safer than manual assembly.

Trait	Grants	Denies
base-read	read_files, search	—
file-authoring	write_files	—
command-execution	execute	—
web-research	web	—
delegation	delegate	—
interaction	interact	—
notebook-editing	notebook	—
no-file-edits	—	write_files
no-commands	—	execute
no-web	—	web
full-access	all capabilities	—

Grant traits expand to the corresponding abstract skills (see table above). Deny traits add the expanded tools to disallowed_tools.

Traits are combined in order. If you need a read-only planner that can browse the web but cannot edit files or run commands:

planner:
  capability_traits:
    - base-read
    - web-research
    - no-file-edits
    - no-commands

Traits merge with explicit tools and disallowed_tools — you can use both in the same agent definition. Explicit tool lists take precedence for additions; deny traits always add to the disallow list.

Policy Fields

policies:
  permissions:
    allow: ["Bash(npm run *)", "WebFetch(api.example.com:*)"]
    ask: ["Bash(git push *)"]
    deny: ["Bash(rm -rf *)", "Write(.env*)"]
    default_mode: acceptEdits
  sandbox:
    enabled: true
    auto_allow_bash: true

Custom Templates

Use --from to initialize from any valid TeamCast YAML file:

teamcast init --from ./my-team-template.yaml

This validates the file against the schema, writes teamcast.yaml, and generates all config files.

Preset Metadata

When sharing presets, you can add optional metadata:

preset_meta:
  author: your-name
  tags: [typescript, fullstack, security]
  min_version: "0.5.0"

Validation

teamcast validate runs 10 validation phases:

• Registry references — all fragments, traits, skills, and environments resolve
• Trait and capability composition — no grant/deny conflicts
• Capability-to-tool mapping — abstract capabilities map to target tools
• Policy coherence — no allow/deny contradictions
• Capability-policy cross-check — capabilities align with policies
• Skill requirements — capabilities, MCP servers, and target compatibility
• Instruction validation — fragment conflicts, heuristic contradiction detection
• Team graph — handoff targets exist, no orphans, reachability verified
• Environment checks — detected and declared environments valid
• MCP server configuration — required servers present, no duplicates
• Policy assertions (when defined in policies.assertions)