My brother runs a large crew of pipelayers. The math they do in the field is genuinely hard. Rolling offsets, fitting angles, engineer tape measurements in decimal feet. I don't understand any of it. But I know how to build apps, so I built him a calculator PWA.

The problem came after launch. Every time he needed something changed, he'd send me a message. "Can you make the font bigger?" "The offset calculator is wrong for 22.5 degree fittings." I'd context-switch out of whatever I was doing, try to understand what he meant, get it wrong the first time, and eventually push a fix days later. I was the bottleneck, and I didn't even understand the domain. He knows what the app needs. I know how to code. But the translation layer between us is lossy.

So I built an agent that cuts me out of the loop. He sends a message describing what he wants, the agent makes the changes, deploys a preview, and waits for his approval before pushing to production. No code. No git. No terminal. Just plain English and a preview link.

This isn't a polished product. It's a starting point. But the decisions behind it are intentional, and I think they're worth walking through.

Why Telegram?

I needed a chat interface that was dead simple to use from a phone in the field. Telegram's Bot API made this straightforward. You create a bot through @botfather, get a token, register a webhook URL, and you're receiving messages as JSON payloads. No app to build, no OAuth flow, no UI framework. The user just opens a chat and starts typing.

The bot becomes the entire interface. My brother doesn't need to know what's behind it.

The Architecture

Here's the full flow:

1. User sends a message to the Telegram bot
2. Telegram POSTs the message to an API Gateway endpoint
3. A Lambda function receives it and invokes an AgentCore Runtime
4. The AgentCore container runs Claude with access to the codebase
5. Claude edits code, validates, builds, and deploys a preview to S3/CloudFront
6. The agent sends status updates and the preview URL back through Telegram
7. User reviews the preview and says "ship it" (or asks for changes)
8. The agent merges to main and cleans up

Everything is defined in a single CDK stack. One cdk deploy creates all the infrastructure.

Claude as a Headless Developer

I chose Claude for the agent because of the Claude Agent SDK. It gives you a headless coding experience out of the box. Claude already knows how to read files, write code, run shell commands, and iterate on errors. I didn't need to build any of that tooling. I just needed to point it at a codebase and give it constraints.

The query function from the SDK is the core of it:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt=message_text,
    options=ClaudeAgentOptions(
        system_prompt=system_prompt,
        allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
        cwd=workspace,
        max_turns=30,
    ),
):
    if hasattr(message, "result"):
        result_text = str(message.result)

That's the whole invocation. Claude gets the user's message, a system prompt with context about the project, and a set of tools it can use. It figures out the rest.

Guardrails Make It Safe

Handing an AI agent the keys to a production codebase sounds risky. It is, if you don't constrain it. The system prompt is where you define what the agent can and can't do:

GUARDRAILS:
1. ONLY modify files in src/ and tests/ directories.
2. ALWAYS run validation before deploying.
3. If validation fails, fix the issues and re-run until it passes.
4. NEVER deploy code that fails validation.
5. Keep changes focused — don't refactor unrelated code.
6. Preserve the engineer tape (decimal feet) convention.
7. Fitting angles are 11.25 / 22.5 / 45 / 90 degrees — don't change these.

Rules 6 and 7 are domain-specific. I don't know pipelaying math, but I know those values are sacred.

The workflow section tells Claude exactly how to validate, build, deploy a preview, and wait for approval:

WORKFLOW:
1. Understand the user's request. If unclear, ask for clarification.
2. Make the changes.
3. Run validation: npm run validate
4. If validation fails, fix and retry (up to 3 attempts).
5. Build and deploy to preview.
6. Share the preview URL.
7. Wait for user approval before merging.

The agent never pushes to main on its own. It always deploys to a preview URL first and waits.

Who Gets Access

Every incoming message goes through an authorization check:

if not is_authorized(message.user_id):
    return {"status": "ignored", "reason": "unauthorized"}

The allowlist is a comma-separated list of Telegram user IDs passed as a CloudFormation parameter at deploy time. Simple, intentional, hard to get wrong.

AgentCore: Ephemeral Compute with Long Runtimes

AI coding agents are slow. They need time to read code, think, write changes, run validation, fix errors, build, and deploy. That can take minutes.

Amazon Bedrock AgentCore gave me exactly what I needed. It spins up a container when a request comes in, keeps it warm for subsequent messages from the same user, and shuts it down after an idle timeout. Session affinity routes subsequent requests from the same session to the same container:

user_id = str(payload.get("message", {}).get("from", {}).get("id", "unknown"))
session_id = f"telegram-user-session-id-{user_id}"

The workspace persists. The conversation history persists. It feels stateful even though the compute is ephemeral.

The Async Trick

Telegram expects a 200 response within seconds. But the agent takes minutes. The solution is an async entrypoint:

@app.entrypoint
def handle_request(payload, context=None):
    message = parse_telegram_message(payload)

    task_id = app.add_async_task(
        f"agent-{message.user_id}",
        {"chat_id": message.chat_id, "user_id": message.user_id},
    )

    threading.Thread(
        target=_run_agent_background,
        args=(message.chat_id, message.user_id, message.text, task_id),
        daemon=True,
    ).start()

    return {"status": "accepted", "task_id": task_id}

The add_async_task call tells AgentCore "I'm not done yet, don't shut down this container." While the agent works, it sends status updates directly to Telegram through the Bot API.

One CDK Deploy

The CDK stack creates: API Gateway endpoint, Lambda relay function, AgentCore Runtime (container built from source), S3 + CloudFront for previews, and a Secrets Manager secret for the GitHub deploy key.

agent_runtime = agentcore.Runtime(
    self, "PipelayerRuntime",
    runtime_name="pipelayer_agent",
    agent_runtime_artifact=agentcore.AgentRuntimeArtifact.from_asset(AGENT_DIR),
    environment_variables={
        "TELEGRAM_BOT_TOKEN": telegram_bot_token.value_as_string,
        "DEV_BUCKET": dev_bucket_name.value_as_string,
        "DEV_CDN_DOMAIN": dev_distribution.distribution_domain_name,
        "GITHUB_DEPLOY_KEY_SECRET": deploy_key_secret.secret_arn,
    },
)

The Real Takeaway

AI agents work best when you constrain them. The guardrails in the system prompt are what make this safe enough to hand to someone who doesn't code. The agent can't touch files outside src/ and tests/. It can't deploy without passing validation. It can't push to production without explicit approval.

My brother doesn't need to understand React, or git, or AWS. He just needs to describe what he wants. The agent handles the rest, within boundaries I set.

If you want to dig into the full implementation, the repo is at github.com/singledigit/pipelayer-agent. It's not perfect, but it works. And my brother ships features now.