{"id":51070810,"url":"https://github.com/amcheste/kagents","last_synced_at":"2026-06-23T10:32:50.246Z","repository":{"id":349039793,"uuid":"1200815741","full_name":"amcheste/kagents","owner":"amcheste","description":"A Kubernetes-native platform for orchestrating AI knowledge work teams. Define teams declaratively, run them on your cluster, deliver results automatically.","archived":false,"fork":false,"pushed_at":"2026-06-08T01:55:33.000Z","size":2269,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T03:21:21.277Z","etag":null,"topics":["agent-orchestration","ai-agents","claude","claude-code","cloud-native","knowledge-work","kubernetes","kubernetes-operator"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amcheste.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-03T21:27:33.000Z","updated_at":"2026-06-02T00:14:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amcheste/kagents","commit_stats":null,"previous_names":["amcheste/claude-teams-operator"],"tags_count":7,"template":false,"template_full_name":"amcheste/repo-template","purl":"pkg:github/amcheste/kagents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amcheste%2Fkagents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amcheste%2Fkagents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amcheste%2Fkagents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amcheste%2Fkagents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amcheste","download_url":"https://codeload.github.com/amcheste/kagents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amcheste%2Fkagents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34686725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","ai-agents","claude","claude-code","cloud-native","knowledge-work","kubernetes","kubernetes-operator"],"created_at":"2026-06-23T10:32:45.030Z","updated_at":"2026-06-23T10:32:50.237Z","avatar_url":"https://github.com/amcheste.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/banner.png\" alt=\"kagents banner\" width=\"800\" /\u003e\n\n# kagents\n\n**Run Claude Code Agent Teams as a Kubernetes operator.**\n\n[![Validate](https://github.com/amcheste/claude-teams-operator/actions/workflows/validate.yml/badge.svg)](https://github.com/amcheste/claude-teams-operator/actions/workflows/validate.yml)\n[![Version](https://img.shields.io/github/v/tag/amcheste/claude-teams-operator?label=version\u0026sort=semver\u0026color=0B0B0C)](https://github.com/amcheste/claude-teams-operator/releases)\n[![License](https://img.shields.io/badge/License-Apache_2.0-1F4D3A.svg)](LICENSE)\n[![Go](https://img.shields.io/badge/Go-1.23-00ADD8)](go.mod)\n\n\u003c/div\u003e\n\n---\n\n\u003e **kagents** is the project brand. The implementation lives in the [`claude-teams-operator`](https://github.com/amcheste/claude-teams-operator) repository and ships under the `claude.amcheste.io/v1alpha1` API group. Documentation site: [kagents.dev](https://kagents.dev) (under construction. See [v0.7.0 milestone](https://github.com/amcheste/claude-teams-operator/milestone/8)).\n\nClaude Code [Agent Teams](https://docs.anthropic.com/en/docs/claude-code/agent-teams) let multiple Claude Code instances collaborate. A lead coordinates work via a shared task list while teammates communicate through peer-to-peer mailboxes. Natively this runs on a single machine using tmux. This operator lifts that pattern into Kubernetes so you can run large-scale agent teams on your cluster.\n\n## Modes\n\nThe operator supports two distinct use cases controlled by a single field in the `AgentTeam` spec:\n\n| Mode | Use when | Key field |\n|------|----------|-----------|\n| **Coding** | Agents work on a git repository | `spec.repository` |\n| **Cowork** | Agents produce documents, reports, emails, analysis | `spec.workspace` |\n\nBoth modes share the same coordination protocol (shared PVCs, mailboxes, task lists) and all Cowork extensions (Skills, MCP servers, approval gates).\n\n## Features\n\n- **Native Agent Teams protocol**. Preserves Anthropic's file-based mailbox and task list format over ReadWriteMany PVCs; no protocol translation\n- **Per-teammate git worktrees**. Each coding agent works on an isolated branch to prevent merge conflicts\n- **Cowork mode**. Mount ConfigMap/PVC inputs and collect outputs without requiring a git repo\n- **Skills as CRD fields**. Mount Claude Code skills from ConfigMaps into each agent's `.claude/skills/`\n- **MCP servers per agent**. Configure Model Context Protocol connections per teammate\n- **Approval gates**. Pause spawning specific teammates until a human applies an annotation\n- **Budget enforcement**. Terminate the team if estimated API cost exceeds a configured limit\n- **Timeout enforcement**. Terminate the team after a configurable wall-clock duration\n- **`dependsOn` ordering**. Spawn teammates only after their declared dependencies complete\n- **Reusable templates**. Define team patterns with `AgentTeamTemplate`, instantiate with `AgentTeamRun`\n\n## Quick Start\n\n### Prerequisites\n\n- Kubernetes 1.28+\n- ReadWriteMany PVC support (NFS, EFS, or a compatible CSI driver. See [ARCHITECTURE.md § Storage Requirements](ARCHITECTURE.md#storage-requirements) for options)\n- Claude Code CLI access (Max subscription or API key)\n- Opus 4.6 model access (required for Agent Teams)\n\n### Install on an existing cluster (Helm)\n\n```bash\n# 1. Install the operator (CRDs + controller + RBAC)\nhelm install claude-teams-operator \\\n  oci://ghcr.io/amcheste/charts/claude-teams-operator \\\n  --namespace claude-teams-system --create-namespace\n\n# 2. Create an API key secret in the namespace where your teams will run\nkubectl create namespace dev-agents\nkubectl create secret generic anthropic-api-key \\\n  --namespace dev-agents \\\n  --from-literal=ANTHROPIC_API_KEY=sk-ant-...\n\n# 3. Apply a sample team\nkubectl apply -n dev-agents -f \\\n  https://raw.githubusercontent.com/amcheste/claude-teams-operator/main/config/samples/auth-refactor-team.yaml\n\n# 4. Watch the team progress\nkubectl get agentteams -n dev-agents -w\nkubectl describe agentteam auth-refactor -n dev-agents\n```\n\n### Local development with Kind\n\nFor contributors and anyone who wants to run the full stack from source:\n\n```bash\n# 1. Create a Kind cluster with NFS provisioner\nmake kind-create\n\n# 2. Build and load images into Kind\nmake docker-build docker-build-runner kind-load\n\n# 3. Install CRDs and deploy the operator\nmake install deploy\n\n# 4. Create your API key secret\nkubectl create secret generic anthropic-api-key \\\n  --namespace dev-agents \\\n  --from-literal=ANTHROPIC_API_KEY=sk-ant-...\n\n# 5. Apply a sample team\nkubectl apply -f config/samples/auth-refactor-team.yaml\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full dev loop (testing, linting, manifest regeneration).\n\n## Example: Coding Team\n\n```yaml\napiVersion: claude.amcheste.io/v1alpha1\nkind: AgentTeam\nmetadata:\n  name: auth-refactor\n  namespace: dev-agents\nspec:\n  repository:\n    url: \"git@github.com:acme/backend.git\"\n    branch: \"main\"\n    credentialsSecret: \"git-credentials\"\n\n  auth:\n    apiKeySecret: \"anthropic-api-key\"\n\n  lead:\n    model: \"opus\"\n    prompt: |\n      Coordinate the migration from JWT to OAuth2.\n      Assign backend-api, frontend-auth, and test-coverage to their tracks.\n      Validate integration when all tracks complete.\n\n  teammates:\n    - name: \"backend-api\"\n      model: \"sonnet\"\n      prompt: \"Implement OAuth2 endpoints. Remove JWT middleware.\"\n      scope:\n        includePaths: [\"src/api/auth/\", \"src/middleware/\"]\n\n    - name: \"test-coverage\"\n      model: \"sonnet\"\n      prompt: \"Write comprehensive tests for the OAuth2 migration.\"\n      dependsOn: [\"backend-api\"]\n\n  lifecycle:\n    timeout: \"2h\"\n    budgetLimit: \"30.00\"\n    onComplete: \"create-pr\"\n    pullRequest:\n      targetBranch: \"main\"\n      titleTemplate: \"feat(auth): migrate from JWT to OAuth2\"\n```\n\n## Example: Cowork Team\n\n```yaml\napiVersion: claude.amcheste.io/v1alpha1\nkind: AgentTeam\nmetadata:\n  name: q3-report\n  namespace: cowork-agents\nspec:\n  workspace:\n    inputs:\n      - configMap: \"quarterly-data\"\n        mountPath: \"/workspace/data\"\n    output:\n      mountPath: \"/workspace/output\"\n      size: \"5Gi\"\n\n  auth:\n    apiKeySecret: \"anthropic-api-key\"\n\n  lead:\n    model: \"opus\"\n    prompt: \"Coordinate the Q3 business report. Assign research, writing, and design.\"\n\n  teammates:\n    - name: \"researcher\"\n      model: \"sonnet\"\n      prompt: \"Analyse the data in /workspace/data and produce a findings summary.\"\n      skills:\n        - name: \"data-analysis\"\n          source:\n            configMap: \"data-analysis-skill\"\n\n    - name: \"email-drafter\"\n      model: \"sonnet\"\n      prompt: \"Draft follow-up emails for all Q3 prospects.\"\n      mcpServers:\n        - name: \"gmail\"\n          url: \"https://gmail.mcp.example.com/mcp\"\n\n  lifecycle:\n    timeout: \"3h\"\n    budgetLimit: \"15.00\"\n    approvalGates:\n      - event: \"spawn-email-drafter\"\n        channel: \"webhook\"\n        webhookUrl: \"https://hooks.example.com/approvals\"\n```\n\nGrant approval after reviewing the researcher's output:\n\n```bash\nkubectl annotate agentteam q3-report \\\n  \"approved.claude.amcheste.io/spawn-email-drafter=true\" \\\n  -n cowork-agents\n```\n\n## CRD Reference\n\n### AgentTeam\n\nThe primary resource. Defines the full team, its workspace, lifecycle, and observability config.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `spec.repository` | `RepositorySpec` | Git repo config (coding mode). Optional when `spec.workspace` is set. |\n| `spec.workspace` | `WorkspaceSpec` | Input/output volumes (Cowork mode). Optional when `spec.repository` is set. |\n| `spec.auth` | `AuthSpec` | API key or OAuth secret reference. |\n| `spec.lead` | `LeadSpec` | Lead agent model, prompt, skills, and MCP servers. |\n| `spec.teammates` | `[]TeammateSpec` | Worker agents with optional `dependsOn`, `scope`, `skills`, `mcpServers`. |\n| `spec.lifecycle.timeout` | `string` | Max duration, e.g. `\"4h\"`. Defaults to `\"4h\"`. |\n| `spec.lifecycle.budgetLimit` | `string` | Max USD spend, e.g. `\"10.00\"`. No limit if unset. |\n| `spec.lifecycle.onComplete` | `string` | `create-pr` \\| `push-branch` \\| `notify` \\| `none` |\n| `spec.lifecycle.approvalGates` | `[]ApprovalGateSpec` | Human-in-the-loop gates before spawning a teammate. |\n\n### AgentTeamTemplate\n\nA reusable team pattern. Does not run on its own. Instantiate with `AgentTeamRun`.\n\n### AgentTeamRun\n\nInstantiates an `AgentTeamTemplate` against a specific repo or workspace.\n\n```yaml\napiVersion: claude.amcheste.io/v1alpha1\nkind: AgentTeamRun\nmetadata:\n  name: q4-security-review\nspec:\n  templateRef:\n    name: fullstack-review\n  repository:\n    url: \"git@github.com:acme/platform.git\"\n    branch: \"release/4.0\"\n    credentialsSecret: \"git-credentials\"\n  auth:\n    apiKeySecret: \"anthropic-api-key\"\n  lead:\n    model: \"opus\"\n    prompt: \"Run a full security, performance, and test quality review.\"\n```\n\n## Status\n\nWatch team progress. The `Ready` column reports `running+completed/total` teammates, so `2/3` means two of three workers are up (or have finished) while one is still spawning or blocked on a dependency:\n\n```bash\nkubectl get agentteams -A\n# NAME           PHASE      READY   TASKS DONE   COST    AGE\n# auth-refactor  Running    2/3     7            $1.42   14m\n# q3-report      Completed  2/2     12           $3.80   2h\n```\n\nInspect details, including operator events emitted at every phase transition:\n\n```bash\nkubectl describe agentteam auth-refactor -n dev-agents\n# Status:\n#   Phase: Running\n#   Ready: 2/3\n#   Estimated Cost: 1.42\n#   Lead:\n#     Pod Name: auth-refactor-lead\n#     Phase: Running\n#   Teammates:\n#     - Name: backend-api,   Phase: Running\n#     - Name: test-coverage, Phase: Waiting  (dependsOn: backend-api)\n# Events:\n#   Normal  Initializing  5m   agentteam-controller  Provisioned PVCs and launched init Job\n#   Normal  Running       4m   agentteam-controller  All agent pods started\n```\n\n## Approval Gates\n\nApproval gates block a teammate from being spawned until a human applies an annotation.\n\n```bash\n# Inspect which teammates are waiting\nkubectl get agentteam my-team -o jsonpath='{.status.teammates[*].pendingApproval}'\n\n# Grant approval\nkubectl annotate agentteam my-team \\\n  \"approved.claude.amcheste.io/spawn-email-drafter=true\"\n```\n\nIf `channel: webhook` is set, the operator POSTs a JSON payload to `webhookUrl` when the gate is triggered, allowing an external system to present the approval to a human and then apply the annotation.\n\n## Documentation\n\nThis README is the entry point. For deeper dives, every topic lives in a dedicated in-repo document:\n\n| Document | Read when you want to… |\n|----------|-----------------------|\n| [ARCHITECTURE.md](ARCHITECTURE.md) | Understand how the operator models Agent Teams. Phase state machine, PVC layout, RWX storage backends, coordination protocol, key design tradeoffs. |\n| [TESTING.md](TESTING.md) | See the test strategy (unit / integration / acceptance / E2E), how to run each suite, and what each one actually verifies. |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Set up a dev environment, run the full build/test loop, follow the branch + PR workflow, and walk through \"How to add a new reconciler feature.\" |\n| [docs/helm-values.md](docs/helm-values.md) | Tune the Helm chart. Every value documented with defaults and production override recipes. |\n| [SECURITY.md](SECURITY.md) | Report a vulnerability or review the project's security policy. |\n| [KUBECON.md](KUBECON.md) | See the talk framing and \"interesting problems\" log. Useful context for why specific architectural choices were made. |\n\n## Development\n\nCommon Makefile targets (full loop in [CONTRIBUTING.md](CONTRIBUTING.md)):\n\n```bash\nmake build        # Build operator binary\nmake test         # Run all tests\nmake lint         # Run golangci-lint\nmake manifests    # Regenerate CRD manifests\nmake generate     # Regenerate deepcopy methods\n```\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famcheste%2Fkagents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famcheste%2Fkagents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famcheste%2Fkagents/lists"}