ABCA

Autonomous Background Coding Agents on AWS

ABCA (Autonomous Background Coding Agents on AWS) is a sample of what a self-hosted background coding agents platform might look like on AWS. Users can create background coding agents, then submit coding tasks to them and the agents work autonomously in the cloud — cloning repos, writing code, running tests, and opening pull requests for review. No human interaction during execution.

The platform is built on AWS CDK with a modular architecture: an input gateway normalizes requests from any channel, a durable orchestrator executes each task according to a blueprint, and isolated compute environments run each agent. Agents learn from past interactions through a tiered memory system backed by AgentCore Memory, and a review feedback loop captures PR review comments to improve future runs.

Users submit tasks through webhooks, CLI, or Slack. For each task, the orchestrator executes the blueprint: an isolated environment is provisioned, an agent clones the target GitHub repository, creates a branch, works on the task, and opens a pull request.

Key characteristics:

• Ephemeral environments — each task starts fresh, no in-process state carries over
• Asynchronous — no real-time conversation during execution
• Repository-scoped — each task targets a specific repo
• Outcome-measurable — the PR is either merged, revised, or rejected
• Fire and forget — submit, forget, review the outcome
• Learns over time — the more you use it, the more it self-improves

Each task follows a blueprint — a hybrid workflow that mixes deterministic steps (no LLM, predictable, cheap) with agentic steps (LLM-driven, flexible, expensive):

1. Admission — the orchestrator validates the request, checks concurrency limits, and queues the task if needed.
2. Context hydration — the platform gathers context: task description, GitHub issue body, repo-intrinsic knowledge (CLAUDE.md, README), and memory from past tasks on the same repo.
3. Pre-flight — fail-closed readiness checks verify GitHub API reachability and repository access before consuming compute. Doomed tasks fail fast with a clear reason (GITHUB_UNREACHABLE, REPO_NOT_FOUND_OR_NO_ACCESS) instead of burning runtime.
4. Agent execution — the agent runs in an isolated MicroVM with persistent session storage for select caches: clones the repo, creates a branch, edits code, commits, runs tests and lint. The orchestrator polls for completion without blocking compute.
5. Finalization — the orchestrator infers the result (PR created or not), runs optional validation (lint, tests), extracts learnings into memory, and updates task status.

For the full architecture, see ARCHITECTURE.md.

ABCA is under active development. The platform ships iteratively — each iteration adds features and builds on the previous one.

See the full ROADMAP for details on each iteration.

This repository ships a Claude Code plugin that provides guided workflows for setup, deployment, task submission, and troubleshooting.

git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git
cd sample-autonomous-cloud-coding-agents
claude --plugin-dir docs/abca-plugin

The --plugin-dir flag tells Claude Code to load the local plugin from the docs/abca-plugin/ directory. The plugin's skills, commands, agents, and hooks will be available immediately.

Tip: If you use Claude Code via VS Code or JetBrains, you can add --plugin-dir docs/abca-plugin to the extension's CLI arguments setting.

Skills (guided multi-step workflows — Claude activates these automatically based on your request):

Agents (specialized subagents, spawned automatically or via the Agent tool):

Hook (runs automatically):

A SessionStart hook advertises available skills and agents so Claude can proactively suggest them when your request matches.

If you're modifying the plugin itself, here's the file layout:

docs/abca-plugin/
  plugin.json                    # Plugin manifest (name, version, description)
  skills/
    setup/SKILL.md               # First-time setup workflow
    deploy/SKILL.md              # CDK deployment workflow
    onboard-repo/SKILL.md        # Repository onboarding workflow
    submit-task/SKILL.md         # Task submission (guided + quick mode)
    troubleshoot/SKILL.md        # Diagnostic workflow
    status/SKILL.md              # Platform health check
  agents/
    cdk-expert.md                # CDK infrastructure specialist
    agent-debugger.md            # Task failure debugger
  hooks/
    hooks.json                   # SessionStart capability advertisement

Key conventions:

• The plugin lives under docs/ to keep documentation and plugin content colocated
• Skills live in subdirectories with a SKILL.md file (not flat .md files)
• Agents are flat .md files with YAML frontmatter
• The hook advertises plugin capabilities only (no project-specific content)

After editing plugin files, restart Claude Code with claude --plugin-dir docs/abca-plugin to pick up changes.

Install mise if you want to use repo tasks (mise run install, mise run build). For monorepo-prefixed tasks (mise //cdk:build, etc.), set MISE_EXPERIMENTAL=1 — see CONTRIBUTING.md.

Follow the Developer Guide to set up your environment and deploy the application to your AWS account. Then, follow the User Guide to learn how to use the system.

A documentation site is available containing all design documents, roadmap and guides to deploy and use the platform. You can access it here.

The example provided in this repository is for experimental and educational purposes only. It demonstrates concepts and techniques but is not intended for direct use in production environments.

This library is licensed under the MIT-0 License. See the LICENSE file.