kelos

Kelos Developing Kelos

Kelos develops itself. Seven TaskSpawners run 24/7, each handling a different part of the development lifecycle — fully autonomous.

| TaskSpawner | Trigger | Model | Description | |---|---|---|---| | kelos-workers | GitHub Issues (actor/kelos) | Opus | Picks up issues, creates or updates PRs, self-reviews, and ensures CI passes | | kelos-pr-responder | GitHub Pull Requests (generated-by-kelos, changes_requested) | Opus | Re-engages on PR review feedback and updates the existing branch incrementally | | kelos-planner | GitHub Issues (/kelos plan comment) | Opus | Investigates an issue and posts a structured implementation plan — advisory only, no code changes | | kelos-triage | GitHub Issues (needs-actor) | Opus | Classifies issues by kind/priority, detects duplicates, and recommends an actor | | kelos-fake-user | Cron (daily 09:00 UTC) | Sonnet | Tests DX as a new user — follows docs, tries CLI workflows, files issues for problems found | | kelos-fake-strategist | Cron (every 12 hours) | Opus | Explores new use cases, workflow improvements, and integration opportunities | | kelos-self-update | Cron (daily 06:00 UTC) | Opus | Reviews and tunes prompts, configs, and workflow files — the pipeline improves itself |

Here's a trimmed snippet of kelos-workers.yaml — enough to show the pattern:

apiVersion: kelos.dev/v1alpha1
kind: TaskSpawner
metadata:
  name: kelos-workers
spec:
  when:
    githubIssues:
      labels: [actor/kelos]
      excludeLabels: [kelos/needs-input]
      priorityLabels:
        - priority/critical-urgent
        - priority/important-soon
      pollInterval: 1m
  maxConcurrency: 3
  taskTemplate:
    model: opus
    type: claude-code
    branch: "kelos-task-{{.Number}}"
    promptTemplate: |
      You are a coding agent. You either
      - create a PR to fix the issue
      - update an existing PR to fix the issue
      - comment on the issue or the PR if you cannot fix it
      ...

The key pattern is excludeLabels: [kelos/needs-input] — this creates a feedback loop where the agent works autonomously until it needs human input, then pauses. Removing the label re-queues the issue on the next poll.

See the full manifest at self-development/kelos-workers.yaml and the self-development/ README for setup instructions.

Why Kelos?

AI coding agents are evolving from interactive CLI tools into autonomous background workers — managed like infrastructure, not invoked like commands. Kelos provides the framework to manage this transition at scale.

• Workflow as YAML — Define your development workflow declaratively: what triggers agents, what they do, and how they hand off. Version-control it, review it in PRs, and GitOps it like any other infrastructure.
• Orchestration, not just execution — Don't just run an agent; manage its entire lifecycle. Chain tasks with dependsOn and pass results (branch names, PR URLs, token usage) between pipeline stages. Use TaskSpawner to build event-driven workers that react to GitHub issues, PRs, or schedules.
• Host-isolated autonomy — Each task runs in an isolated, ephemeral Pod with a freshly cloned git workspace. Agents have no access to your host machine — use scoped tokens and branch protection to control repository access.
• Standardized interface — Plug in any agent (Claude, Codex, Gemini, OpenCode, Cursor, or your own) using a simple container interface. Kelos handles credential injection, workspace management, and Kubernetes plumbing.
• Scalable parallelism — Fan out agents across multiple repositories. Kubernetes handles scheduling, resource management, and queueing — scale is limited by your cluster capacity and API provider quotas.
• Observable & CI-native — Every agent run is a first-class Kubernetes resource with deterministic outputs (branch names, PR URLs, commit SHAs, token usage) captured into status. Monitor via kubectl, manage via the kelos CLI or declarative YAML (GitOps-ready), and integrate with ArgoCD or GitHub Actions.

Quick Start

Get running in 5 minutes (most of the time is gathering credentials).

Prerequisites

• Kubernetes cluster (1.28+)

1. Install kind (requires Docker)
2. Create a cluster:

   kind create cluster
   

This creates a single-node cluster and configures your kubeconfig automatically.

1. Install the CLI

curl -fsSL https://raw.githubusercontent.com/kelos-dev/kelos/main/hack/install.sh | bash

go install github.com/kelos-dev/kelos/cmd/kelos@latest

2. Install Kelos

kelos install

This installs the Kelos controller and CRDs into the kelos-system namespace.

Verify the installation:

kubectl get pods -n kelos-system
kubectl get crds | grep kelos.dev

Helm Install

Kelos also publishes a Helm chart as an OCI artifact in GHCR.

To install Kelos with Helm:

helm upgrade --install kelos oci://ghcr.io/kelos-dev/charts/kelos \
  -n kelos-system \
  --create-namespace \
  --version <version>

This installs the controller and, by default, the Kelos CRDs.

For CRD migration, adopting existing CRDs into Helm ownership, and advanced chart usage, see the Helm chart README.

3. Initialize Your Config

kelos init

Edit ~/.kelos/config.yaml:

oauthToken: <your-oauth-token>
workspace:
  repo: https://github.com/your-org/your-repo.git
  ref: main
  token: <github-token>  # optional, for private repos and pushing changes

Claude OAuth token (recommended for Claude Code): Run claude setup-token locally and follow the prompts. This generates a long-lived token (valid for ~1 year). Copy the token from ~/.claude/credentials.json.

Anthropic API key (alternative for Claude Code): Create one at console.anthropic.com. Set apiKey instead of oauthToken in your config.

Codex OAuth credentials (for OpenAI Codex): Run codex auth login locally, then reference the auth file in your config:

oauthToken: "@~/.codex/auth.json"
type: codex

Or set apiKey with an OpenAI API