@@ -0,0 +1,13 @@
+Copyright 2026 Bold Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
@@ -1,70 +1,49 @@
-# Shelley - A Coding Agent for exe.dev
+# Shelley: a coding agent for exe.dev
-Shelley is a conversational AI coding agent that provides a web interface
-for AI-powered coding assistance.
+Shelley is a mobile-friendly, web-based, multi-conversation, multi-modal,
+multi-model, single-user coding agent built for but not exclusive to
+[exe.dev](https://exe.dev/). It does not come with authorization or sandboxing:
+bring your own.
-See also ARCHITECTURE.md for architectural details.
+*Mobile-friendly* because ideas can come any time.
-## Dev Tricks
+*Web-based*, because terminal-based scroll back is punishment for shoplifting in some countries.
-If you want to see how mobile looks, and you're on your home
-network where you've got mDNS working fine, you can
-run
- socat TCP-LISTEN:9001,fork TCP:localhost:9000
-and then have your phone go to http://hostname.local:9001/
+*Multi-modal* because screenshots, charts, and graphs are necessary, not to mention delightful.
-## CLI Usage
+*Multi-model* to benefit from all the innovation going on.
-Shelley can be used as a command-line tool with the following commands:
+*Single-user* because it makes sense to bring the agent to the compute.
-### Global Flags
+# Architecture
-- `--db <path>`: Path to SQLite database file (default: "shelley.db")
-- `--model <model>`: LLM model to use (use `predictable` for testing). Run `shelley models` to see available models.
-- `--debug`: Enable debug logging
+The technical stack is Go for the backend, SQLite for storage, and Typescript
+and React for the UI.
-### Commands
+The data model is that Conversations have Messages, which might be from the
+user, the model, the tools, or the harness. All of that is stored in the
+database, and we use a SSE endpoint to keep the UI updated.
-#### `serve` - Start Web Server
+# History
-Starts the web server for the browser-based interface.
+Shelley is partially based on our previous coding agent effort, [Sketch](https://github.com/boldsoftware/sketch).
-```bash
-shelley serve --port 9000
-```
+Unsurprisingly, much of Shelley is written by Shelley, Sketch, Claude Code, and Codex.
-Flags:
-- `--port <port>`: Port to listen on (default: 9000)
-
-#### `models` - List Supported Models
-
-Lists all supported models and their required environment variables.
-
-```bash
-shelley models
-```
+# Open source
-### Examples
+Shelley is Apache licensed. We require a CLA for contributions.
-```bash
-# Start the web server
-shelley serve --port 8080
+# Building Shelley
-# List supported models
-shelley models
+Run `make`. Run `make serve` to start Shelley locally.
-## Models and API Keys
-
-Use `shelley models` to see supported models, whether they are ready, and the environment variables required for each.
-
-Common env vars:
-
-- `ANTHROPIC_API_KEY`: Required for Claude models.
-- `OPENAI_API_KEY`: Required for OpenAI models.
-- `FIREWORKS_API_KEY`: Required for Fireworks models.
+## Dev Tricks
-Notes:
+If you want to see how mobile looks, and you're on your home
+network where you've got mDNS working fine, you can
+run
-- Run `shelley models` to see which model is the default and which are available.
-- `predictable` is a built-in test model and requires no API keys.
+```
+socat TCP-LISTEN:9001,fork TCP:localhost:9000
```