y-cli 🚀

y-agent

One Entry Point, a Cloud Workspace

Hand over a task from your phone, tablet, or desktop. Let the agent work in the same cloud workspace, and come back when there's a decision to make or work to check.

I keep the workspace on EC2 and use y-agent as one entry point. Telegram is another way into the same system, not a separate mobile agent. Code, notes, task records, and results stay in my own workspace rather than belonging to a particular chat window. Switching devices doesn't mean introducing the project all over again.

Read the full story: My AI Dev Setup: One Entry Point, a Cloud Workspace.

How it fits together

These are the layers of my deployment, not five services in a linear pipeline:

Layer	Role	My setup
Client	Hand over tasks and read results	y-agent web UI, with Telegram as a chat input interface
Memory	Keep project context and task state	Files on EC2; structured records in PostgreSQL on RDS
Runtime	Read code, edit files, run commands	Claude Code on EC2
Gateway	Connect and forward model requests	A self-hosted relay: my fork of claude-relay-service
Models	Supply model capabilities	Claude / GPT / Grok

Files and database records are read and written as work needs them. They aren't a stop every model request passes through. The runtime and model source are separate choices: Claude Code is the only agentic CLI backend in this repository. Other model sources depend on the configured gateway, interface compatibility, and provider subscription terms; a subscription isn't a general-purpose API entitlement. The relay is a separate service, not bundled with y-agent. Model context still leaves the workspace for inference.

Under the hood, a React web UI and Telegram feed a FastAPI API. The API queues work through SQS to a worker, which starts Claude Code over SSH in EC2 tmux sessions and streams results back into chat records. API, worker, and admin jobs deploy with AWS SAM/Lambda; PostgreSQL holds structured state. Local development uses Celery with a filesystem broker instead of SQS.

What it does

• One workspace beyond code. Work with todos, notes, links, calendars, email, and domain modules through the web and y CLI. The agent uses the same files and records, rather than a separate copy of your context.
• Task-linked context. A todo connects discussions, plans, progress, and reviews. A new session reads that material instead of needing the entire previous conversation in its prompt.
• Orchestration outside the runtime. One session can finish a small task; larger tasks can split into planning, implementation, and review sessions, each loading the skill it needs. A shared trace_id connects the tree, and sub-task chats remain visible and steerable.
• An inbox for your turn. awaiting marks work needing a decision, authorization, or acceptance check. Publication approval is a separate boundary from implementation and review.
• Extensible surfaces. Hot-loadable modules can add UI, API, CLI, and data. Chat can render Mermaid diagrams, Vega-Lite charts, and sanitized SVG artifacts. See the module contract.
• MCP connectors. Connect remote HTTPS MCP servers (OAuth, static header, or no auth; Alpha Vantage first) once (OAuth via y mcp connect loopback login), approve tools explicitly, and every Claude Code session gets them from its next launch. Credentials stay central in the API and are never returned by any read; sessions only see approved tools through a launch-scoped gateway. See the MCP connectors PRD and runbook.

See a real task trace.

Get started

This is my personal system, not a hosted service or a supported product. It is not supported for public use or third-party deployment.

If you're an advanced user who wants to deploy your own, use this project as a reference, not a turnkey installation guide. Expect to adapt the code and infrastructure to your environment and maintain them yourself.

Domain modules live in a separate y-module repository; their source and published bundles are not included in this checkout. Backups, permissions, provider access, and infrastructure maintenance remain yours to manage.

More

• CHANGELOG: release history.
• Earlier y-agent introduction: background and design rationale.
• Formerly y-cli: y-cli wrapped model APIs; y-agent wraps coding agents.