Under the hood
Decisions
Why Conch is built the way it is. One record per decision, newest first.
A change to the architecture, or a new dependency of any weight, starts as a record in docs/adr. Each says what was decided, what else was considered, and what it costs.
- 0152 — The key to your passwords stays with the operating system
- 0151 — A saved key in a command, unseen
- 0150 — Measuring how often Auto asks
- 0149 — Auto learns your environment
- 0148 — The sealed box reaches registries
- 0147 — Fast reviews on every provider
- 0146 — One Auto review per action
- 0145 — Auto reads intent in every language
- 0144 — Task-aware Auto review
- 0143: Question answers resume the chat
- 0142: Recovering a stuck app sign-in
- 0141 — A browser per errand
- 0140 — The always-on relay
- 0139 — Searching chats by meaning
- 0138 — Phone calls on the SMS number
- 0137 — Auto uses current evidence; wait notifications choose one destination
- 0136 — Review skill updates in chat
- 0135 — Modes without surprise approvals
- 0134 — Chats that know about each other
- 0133 — How an account signs in
- 0132 — Switching models when asked
- 0131 — Everyday browsing: the page's questions, long forms, long pages, bot checks, find, Stop
- 0130 — Passwords in the browser
- 0129 — Tasks start when there's room, and say why they wait
- 0128 — Auto reads what you asked for
- 0127 — Releasing with release-please: a release pull request, a tag signed in CI
- 0126 — At a limit, the next one with room
- 0125 — Waiting without polling: Conch watches, the model sleeps
- 0124 — Drafts that follow you, with their files
- 0123 — A script that calls your tools, one story in the chat
- 0122 — Any provider, any chat app
- 0121 — Dashboards: Conch's numbers and traces, over OpenTelemetry and Prometheus, private by default
- 0120 — Feishu / Lark, DingTalk and QQ: the chat apps of China's workplaces, outward only
- 0119 — Four modes, Auto by default
- 0118 — Auto judges every app's step by what it does, and is Conch's own on every provider
- 0117 — Auto asks about what matters, and watches what a chat does
- 0116 — Type at the size it says, and a reading size for the chat
- 0114 — Money, charts, and sharing a card
- 0113 — How it did it: a run's timeline, and saving it as a trajectory
- 0112 — Agents that talk to each other
- 0111 — Your past chats from other apps
- 0110 — Using your apps, while you watch
- 0109 — Your company's cloud: Bedrock, Vertex AI and Azure OpenAI, from the sign-ins already here
- 0108 — The phone, without native apps: approve from the notification, “Hey Conch” while it’s open
- 0107 — Check-ins, standing orders and the morning's note
- 0106 — Where work runs: a container, your machine, the cloud
- 0105 — Rich cards in the chat
- 0104 — Gmail sends when it says it can
- 0103 — The chat tells what the assistant is doing
- 0102 — Every assistant works the problem
- 0101 — Agents: several assistants, one Conch
- 0100 — Permission modes that mean the same with every provider
- 0099 — Many Google accounts, each with read or write access
- 0098 — Chat commands every provider understands: /clear, /goal, /plan, and a menu that completes
- 0097 — Proactive memory maintenance
- 0096 — Bounded browser steps
- 0095 — Independent reads during browser waits
- 0094 — Staying responsive and recovering safely
- 0093 — A website that follows the version people install
- 0092: App page state and queries
- 0091 — Settings from chat apps
- 0090 — An app's picture as its icon
- 0089 — The chat list, organised: status at a glance, pins, folders, apps that look like apps
- 0088 — Quiet learning: learned while you're away, said afterwards, undone in one press
- 0088 — Everyday tools for every model
- 0087 — The memory check: a memory that looks planted is asked about
- 0086 — Lean mode: Conch for a model that reads little at once
- 0085 — Long jobs that finish and cost less: a turn budget, prompt caching, pages that say what changed
- 0084 — Google Chat: a Chat app of your own, through the public door
- 0083 — Rocket.Chat: a bot on your own server, over its realtime API
- 0082 — LINE: an Official Account of your own, through the public door
- 0081 — Mattermost: a bot on your own server, over its WebSocket
- 0080 — The browser does what you do, where you choose
- 0079 — What a chat costs, and the limits that hold it
- 0078 — “Hey Conch”: a wake word that stays on your computer
- 0077 — Voice notes, a natural voice, and talking over it
- 0076 — SMS: a phone number of the assistant's own, through Twilio
- 0075 — Group chats: answered when asked, and only you can ask it to act
- 0074 — Discover: skills people share, read before they're added
- 0073 — Conch for your other apps: an MCP door, paired by you
- 0072 — Every model gets its tools
- 0071 — Evals on every model
- 0070 — Every model sees the page
- 0069 — Carrying a chat on, on every provider
- 0068 — A welcome, not a task
- 0067 — Your address through a tunnel or web server you already run
- 0066 — Codex CLI, and coding agents as their own kind of provider
- 0065 — Passkeys, and approving new devices from your own
- 0064 — Your own address: HTTPS by Conch itself, and a link that makes it yours
- 0063 — "This computer" is proven, not guessed from the address
- 0062 — Copy to another password manager, and Passwords you can work in
- 0061 — Apps you make, share and add
- 0060 — The chat knows Conch
- 0059 — Looking through earlier chats
- 0058 — Skills from what worked, and a tidy shelf
- 0057 — Routines can't run up a bill or eat your plan
- 0056 — Routines that start from what happens, and a pulse that costs nothing
- 0055 — Long chats on every model: summarise the start, learn it first, heal "too long"
- 0054 — The desktop app: Conch as a download, for Mac, Windows and Linux
- 0053 — More providers: the plans you pay for, every key, and servers of your own
- 0052 — One app, one card
- 0051 — Releases: pnpm release, channels, signed tags and the staged swap
- 0050 — Models that can't use apps
- 0049 — Every app works with every model
- 0048 — Google apps as apps, and Gmail with an app password
- 0047 — Skill scope: held for the whole chat, and a signing key locked to this computer
- 0046 — Edit by hand and live data: closing what Show me left open
- 0045 — Microsoft Teams, Matrix and WeChat, and the public door
- 0044 — iMessage and email: channels through accounts that are already yours
- 0043 — WhatsApp and Signal: your own account, linked by QR code
- 0042 — Come home, the rest: the model, other agents, a Slack bot with one key
- 0041 — Meaning out of the box: Conch's own small model, and habits however you word them
- ADR 0040 — Google setup without a hosted connection service
- 0039: A useful result before personalization
- 0038 — Durable verified tasks
- ADR 0037 — Google accounts belong to Conch
- 0036 — Conch owns tool execution and the ChatGPT connection
- 0035 — Come home: bring your things from OpenClaw and Hermes
- 0034 — Show me: things made beside the chat, sealed pages, pinned apps
- 0033 — Hand it off: background tasks and helpers side by side
- 0032 — It learns you: meaning search, a tidy-up you can undo, skills you keep asking for
- 0031 — Skill trust: what a skill may do, who made it, sealed in every provider
- 0030 — Undo: every file the assistant changes can be put back
- 0029 — In the menu bar, and a little computer
- 0028 — Safe hands: checking after reading, sealed commands, activity, skills read first
- 0027 — In your pocket: the phone's secure address, the app, notifications and voice
- 0026 — Just open it: the installer, Always on, and Conch as an app
- 0025 — Passwords: a vault of your own, and the managers you already use
- 0024 — Devices, and approving new ones
- 0023 — Offline and at a limit: answer, or wait
- 0022 — A model on this computer
- 0021 — Connect an app from the chat
- 0020 — Backups: your Conch in one file, and back again
- 0019 — Updates: quiet checks, one-click updates, Conch updating itself
- 0018 — Channels: reaching your assistant from Telegram, Discord and Slack
- 0017 — Attachments: long pastes, files and pictures
- 0016 — Getting what a feature needs
- 0015 — The terminal
- 0014 — The browser
- 0013 — Skills
- 0012 — Every provider at once
- 0011 — Authenticated reverse-proxy deployment
- 0010 — Providers
- 0009 — Integrations
- 0008 — Access: sign-in, sessions and gateway hardening
- 0007 — Search
- 0006 — Routines (scheduled tasks)
- 0005 — Usage limits
- 0004 — Engines
- 0003 — Memory
- 0002 — Nacre design system
- 0001 — Monorepo & tooling