A personal assistant you install with one command

1. D1

   One small package

   Python 3.11+, installed with uv, running as one asyncio process. All state lives in ~/.attache, or wherever ATTACHE_HOME points. The same package runs in Docker later.

2. D2

   Every optional capability is a skill

   One folder of Agent Skills directories holds four kinds of skill: knowledge, scripts, channels and artifact templates. The core never learns about Gmail or Slack.

3. D3

   Skills are living documents

   The agent edits a skill when you change how you work. ~/.attache is a git repo, so every edit is a commit you can read and undo. Only your own messages can change a skill.

4. D4

   Model backends are config rows

   Four small adapters: anthropic, openai-chat, openai-responses and claude-cli. Any endpoint that speaks one of those protocols is one block of TOML. Your own chats use your Claude login, and group chats use an API key. No LiteLLM and no agent framework.

5. D5

   Channels run as sidecar processes

   Each channel skill ships a channel.py that uv runs with its own dependencies. It talks to the core in JSON lines over stdin and stdout. Slack and Signal come first. Each sidecar shows approval requests its own way: buttons in Slack, a reaction prompt in Signal.

6. D6

   Artifacts are local pages over real data

   The agent writes HTML. The built-in server adds a small attache bridge to the SQLite store, with live updates. People in chat apps get a PNG snapshot and a signed link.

7. D7

   Group chats follow a fixed policy

   Access, then trigger, then role. Each role has its own toolset, and a guest's turn never has private data and outbound sending at the same time.

8. D8

   Three surfaces, each with one job

   The CLI sets up and operates. One local web page holds chat and artifacts. Chat apps cover the phone and the group.

9. D9

   Size is a test

   CI fails if the core passes 2,860 lines of code. Blank lines, comments and docstrings don't count, so the budget never rewards dense code. New features arrive as skills, and the contribution guide says so.

10. D10

    One mail skill for every account

    Outlook through Outlook classic's COM interface or Microsoft Graph with OAuth, your choice per account. Gmail and Titan over IMAP. All behind the same commands. It reads and files on its own, saves replies as drafts, and sends only after your yes.

I read nanoclaw at three points in its history: the first week, the v1.2.0 tag and today's v2. I also looked at OpenClaw, the project nanoclaw was written in reaction to, and at nanobot, the best-known Python project in this space.

“Accepted: Bug fixes, security fixes, simplifications, reducing code. Not accepted: Features, capabilities, compatibility, enhancements. These should be skills.” (nanoclaw, CONTRIBUTING.md)

One process. Channels feed a router, the router builds a turn, a backend runs it, and tools act on the world. All state lives in one folder and one SQLite file.

One message, start to finish

1. Jo writes “@Attaché can you send the packing list as a PDF?” in the family Signal group. The Signal sidecar, a thin wrapper around signal-cli's JSON-RPC mode, turns it into one JSON line on its stdout.
2. The router checks that the chat is allowed, sees the mention and looks Jo up as a member. Members can use this chat's files, send to this chat only, use shared collections and make artifacts.
3. It builds the turn: the persona, this chat's memory file, the full text of the skills members may use, the last 30 messages with other people's words fenced and labelled as data, and Jo's identity taken from the config. Your own USER.md stays out of anyone else's turn.
4. The backend runs the loop. The model follows the pdf skill, runs its script through the script tool (which uses uv run), and calls send with the file.
5. The core writes a send line to the sidecar's stdin, and the bot posts the PDF to the group with a caption.

A skill is a folder with a SKILL.md, following the Agent Skills standard that Claude Code, Codex and others read. Only each skill's name and description go into the prompt, about a hundred tokens each. The agent opens the full file when a task needs it, so forty skills cost less than one long system prompt.

attache.toml          endpoints, people, chats
attache.db            messages, docs, tasks
memory/
  USER.md             who you are, VIPs, tone
  chats/family.md     one file per chat
skills/
  mailbox/            knowledge: yours
    SKILL.md
  mail/               script: Outlook, IMAP
    SKILL.md
    accounts.toml
    mail.py           PEP 723: pywin32, imapclient
  todos/              lists, fields, habits
  docx/               script
    SKILL.md
    scripts/make.py   PEP 723: python-docx
  slack/              channel
    SKILL.md
    channel.py
  signal/             channel, wraps signal-cli
  artifact-kit/       templates
    SKILL.md
    tokens.css
    templates/board.html
artifacts/
  todo-board.html

---
name: mailbox
description: How I file and triage my email.
  Use when sorting, archiving, drafting replies
  or summarising the inbox.
metadata:
  attache-owner-only: "true"
---
# Mailbox

## Accounts
- outlook: personal
- gmail: shopping, newsletters
- titan: business

## Folders
- Finance/Receipts: receipts, invoices
- Family: Sam, Jo, school
- Reading: newsletters worth keeping

## Each morning at 07:30
1. List unread mail in every account.
2. File anything matching a rule below.
3. Flag mail from VIPs in USER.md.
4. Draft replies I'll need. Never send.
5. Post a five-line summary to my Slack DM.

## Learned rules
<!-- appended when you correct me -->
- Substack goes to Reading. (12 Oct)

How a skill changes itself

$ attache skills log mailbox
a41c9e2 mailbox: Amazon receipts → Finance/Amazon
        you, Slack DM, 19 Oct 09:14

 ## Folders
-- Finance/Receipts: receipts, invoices
+- Finance/Receipts: receipts, invoices (not Amazon)
+- Finance/Amazon: Amazon receipts and orders

• Only turns from the owner can write under skills/. When a member asks for a change, such as “always send the shopping list as a checklist”, the assistant drafts the edit and sends it to your DM for a yes or no.
• After any turn that touched skills/ or memory/, the core commits with the request as the message. attache skills undo mailbox reverts the last change.
• attache init copies the bundled skills into your folder. Upgrades to them arrive as a git merge, so your edits stay.
• A bundled skill-writer skill lets the agent create new skills from a conversation, as nanobot's skill-creator does.
• New abilities arrive the same way. Asked to “add Signal”, the agent drafts skills/signal/ with a channel.py that talks to signal-cli. You review the commit, and it starts on the next restart.

One mail skill gives the agent the same commands for all three accounts. Behind them sit three backends. Outlook uses either Outlook classic on this PC through its COM interface, or Microsoft Graph with an OAuth sign-in; you pick per account. Gmail and Titan use IMAP with SMTP. Your filing rules live in the mailbox knowledge skill, so they don't change with the backend.

Outlook.com and Microsoft 365 refuse password sign-in over IMAP, so the Outlook account goes through Outlook classic or through Graph. The Gmail and Titan passwords are kept in Windows Credential Manager through keyring, never in a config file or in git.

Outlook: COM or Graph

Start with COM, since there is nothing to register. Switch the Outlook account to Graph when you want it to work with Outlook closed, on another machine or in the cloud. The switch is one line in accounts.toml, and the mailbox skill doesn't change. The app ID is a public value, not a secret, so the project could register one app and ship its ID. Until it does, you register your own.

[outlook]
backend = "com"     # or "graph", which also needs:
# client_id = "<your app ID>"

[gmail]
backend = "imap"
imap    = "imap.gmail.com:993"
smtp    = "smtp.gmail.com:465"
user    = "you@gmail.com"

[titan]
backend = "imap"
imap    = "imap.titan.email:993"
smtp    = "smtp.titan.email:465"
user    = "you@yourdomain.com"

$ uv run mail.py inbox --account all --unread
{"ok": true, "items": [
 {"id": "ol:AAAAAJ3pQ…", "account": "outlook",
  "subject": "Boiler service quote",
  "from": {"name": "Dan Price",
           "smtp": "dan@example.com"},
  "received_utc": "2026-10-18T16:42:00Z",
  "preview": "Hi, attached is the quote…",
  "untrusted": true},
 {"id": "gm:1801234567890123456",
  "account": "gmail",
  "subject": "Your order has shipped", …}]}

Limits to plan for

• Only classic Outlook has COM; the new Outlook app has none. If you switch, mail doctor says so; set the account to Graph and it carries on. Microsoft supports existing classic installs until at least 2029.
• Attaché has to run in your own logged-in session without elevated rights. Windows refuses the connection when one side is elevated and the other isn't, and Microsoft doesn't support Office automation from background services. attache service install sets up the scheduled task this way.
• Outlook shows security prompts when antivirus isn't reported healthy or a policy forces them. On a home PC with Defender up to date it is normally silent.
• Outlook updates occasionally break COM. An April 2026 Current Channel build did until Microsoft fixed it in May, which is one reason doctor exists.
• A Graph sign-in lapses after 90 days without use or when you change your Microsoft password, and some work tenants block sign-in to unverified apps. doctor names the cause and asks you to run login again.
• Gmail revokes app passwords whenever you change your Google password. doctor spots the failed sign-in and asks you for a new one.
• Titan caps mail to outside addresses by plan, from 50 an hour on Starter. Approved sends are few, but the skill still counts recipients and limits each run.

Budget: built at 1,349 lines in four files (shared commands and IMAP about 655, COM and Graph about 695), against a cap of 1,350, raised from the 1,200 first estimated; headers and free/busy status for the email channel and the diary later took it to 1,381, under a cap of 1,390. It is the biggest skill, and it is still outside the core. Early open-source Outlook MCP servers such as outlook-classic-mcp and Robvred/outlook-mcp are useful for patterns: one Outlook thread, draft-only defaults and an audit log.

Two kinds of backend sit behind one interface. API backends return a model response, and Attaché runs the tool loop. CLI backends run their own loop and call Attaché's tools through MCP.

[routing]
own_chats   = "claude"      # your Claude login
group_chats = "claude-api"  # API key

[endpoints.claude]
api   = "claude-cli"          # your Claude Code login
model = "claude-sonnet-5-5"

[endpoints.claude-api]
api     = "anthropic"
model   = "claude-sonnet-5-5"
key_env = "ANTHROPIC_API_KEY"

[endpoints.openai]
api     = "openai-responses"
model   = "gpt-5.4"
key_env = "OPENAI_API_KEY"

[endpoints.local]
api      = "openai-chat"
base_url = "http://localhost:11434/v1"
model    = "qwen3:32b"

class Backend(Protocol):
    async def run(self, turn: Turn) -> Reply: ...

async def tool_loop(complete, turn, steps=20):
    msgs = turn.history + [user(turn.text)]
    for _ in range(steps):
        out = await complete(turn.system, msgs,
                             turn.tools)
        msgs.append(out.message)
        if not out.calls:
            return Reply(out.text)
        msgs.append(await run_tools(out.calls, turn))
    return Reply("I stopped after 20 steps.")

• Official SDKs only. anthropic and openai together resolve to 17 packages. LiteLLM resolves to 59, shipped 241 releases in 2026, and had two compromised PyPI releases (1.82.7 and 1.82.8) on 24 March 2026. nanobot replaced it with the two SDKs that day.
• Why two OpenAI adapters. From GPT-5.4 on, Chat Completions only allows tool calls when reasoning_effort is none, so OpenAI's own reasoning models need Responses. Local and hosted compatible servers mostly speak Chat Completions.
• How claude-cli works. It runs claude -p --output-format stream-json --verbose --resume <session> in a folder outside your home, keeps one Claude session per chat, and points --mcp-config at an MCP endpoint on the local web server, which serves only Attaché's own tools (Claude Code brings its own file and shell tools). When a session starts fresh it gets the earlier conversation as a transcript. It only answers your own chats, never a group. The claude-agent-sdk package does the same thing in-process, but it bundles the CLI (104 to 117 MB per platform wheel), so it stays an optional extra.
• Subscriptions. Anthropic's terms allow a Pro or Max login for your own individual use. Anything that serves other people should use an API key. Your choice follows that: claude-cli on your login for your own chats, claude-api with a key for group chats. A chat can still name its own endpoint. If ANTHROPIC_API_KEY is set, claude -p uses it instead of your login.

An artifact is an HTML file the agent writes into artifacts/. The local server serves it with a small bridge script, so a to-do board edits the real to-do collection. An open page updates when the agent or someone else changes the data. Try the example below; the log on the right shows the calls the page would make.

const todos = await attache.db.list("todos",
                {list: "Home"})
await attache.db.put("todos", id,
                {...t, status: "done"})
attache.on("todos", render)   // live, over SSE
// in the Attaché window: a turn with db on this page's data
const answer = await attache.ask("Suggest three more items")

Generated pages share the design tokens in artifact-kit, so they look like one product. Ask for a different look and the agent edits the kit.

In a group anyone can talk to Attaché, so the router settles three questions in a fixed order before a model sees anything.

1. 1 · ACCESS

   Is this chat allowed?

   Chats and people are listed in attache.toml, keyed by platform IDs, never display names. Unknown chats are ignored.

2. 2 · TRIGGER

   Was Attaché addressed?

   A mention, a reply to the bot, or the chat's pattern. Other messages are stored as context and never answered.

3. 3 · ROLE

   Who is asking?

   Owner, member or guest. The role decides which tools the turn gets.

Shared lists

Members of a chat can tick off items on any list shared with that chat. Both ways of ticking update the same record, so every open copy of the list changes at once.

• In the chat: “@Attaché tick off passports”. The tick is credited to the sender, because the router knows who they are.
• On the list's page, from the link the bot posted. That link can change only that list, expires, and can be revoked. Ticks made there are logged as “via the Family link”, because a shared link can't tell people apart.
• Members can add items too. Only you can delete a list, change who it is shared with or revoke its link. If you'd rather members only tick, that is one setting.

Slack and Signal

Both run as sidecars with the same protocol, so the core treats them alike. They suit different people: Slack for you and colleagues, Signal for family and friends.

# attache → channel
{"type": "ask", "chat_id": "D07…", "ask_id": "a19",
 "text": "Jo wants shopping lists as checklists. Update the skill?",
 "options": ["Approve", "Decline"]}

# channel → attache
{"type": "answer", "ask_id": "a19",
 "sender_id": "U04…", "choice": "Approve"}

You weren't sure whether people should use a CLI or a web interface. My recommendation is three surfaces, each with one job, and none of them heavy.

$ uvx attache init
? Your name › Alex
? Model › claude-cli (your Claude Code login)
? Chat apps › slack, signal
  Slack: create the app from attache-slack.yml
  Bot token (xoxb-…) › ••••••••
  App token (xapp-…) › ••••••••
  Signal needs Java 25. Install with winget? › yes
  Number for the bot › +44 7700 900123
  Captcha from signalcaptchas.org › ••••••••
  Code from the SMS › ••••••
✓ Wrote ~/.attache/attache.toml
✓ Copied 11 starter skills
✓ Started a git repo in ~/.attache

$ attache run
  Open http://127.0.0.1:8765/#t=…
  chats  terminal, slack (3), signal (2)
  tasks  3 scheduled, next 07:30

Phase 1 came in at 1,576 lines of code in src/attache, against a cap of 1,600 that CI enforces. Phase 2 added the sidecar runner, approvals, rate limits and the hardening its reviews asked for. The simplicity review cut 54 lines first, and the owner then raised the cap to 1,900, with a target of about 1,850. For phase 3 the owner raised it to 2,050, then to 2,100 for the review fixes: sharing, attache.ask from pages, persisted requests and their hardening. The terminal's progress work then raised it to 2,180, and email requests to 2,240, for script identity and background runs. The owner workspace adds validated configuration editing, safe source preservation and recovery, raising the cap to 2,700. Starting a chat afresh (/new) and long turns, which wind up on a loop and carry on in a fresh context, raised it to 2,710. The owner's model keyring plan adds 148 core code lines and raises the cap to 2,860; the core is at 2,850. Login, rotation, status and logout live in the credentials skill, at 180 lines. The optional Hailer adapter remains a skill. Mail, files, the triage and the service are all skills. Blank lines, comments and docstrings don't count, so the budget never pushes code to be denser than it should be. Bundled skills, static files and tests don't count either, but each bundled skill has its own cap: 300 lines by default, 1,390 for mail, which has three backends, and 310 for tui, which clears its screen on /new.

[project]
name = "attache"
requires-python = ">=3.11"
dependencies = [
  "anthropic", "openai",
  "starlette", "uvicorn",
  "pyyaml", "cronsim",
  "keyring>=25,<26",
]

[project.optional-dependencies]
claude-sdk = ["claude-agent-sdk"]

[project.scripts]
attache = "attache.cli:main"

CORE_LIMIT = 2860  # blanks, comments, docstrings free

def test_core_stays_small():
    lines = sum(code_lines(p) for p in core_files())
    assert lines <= CORE_LIMIT, (
        f"core is {lines} lines of code; "
        "move the feature into a skill")

1. PHASE 1Local core

   Package skeleton and budget test, config, store, terminal and web chat, the four adapters, tools, the skills folder with git, the scheduler, the todos skill and the Home artifact.

   Done whenuvx attache gives a working assistant on localhost with to-dos and reminders.

   Built: pull request #28, version 0.0.1.

2. PHASE 2Messaging

   The sidecar protocol with approval requests, the slack and signal skills, router policy and roles, file sending, the render skill for PNG and PDF.

   Done whenyou approve actions from a Slack DM, and a family Signal group can ask for answers, files and a shared checklist.

   Built: pull request #34. Tested offline with a fake channel; the run against real Slack and Signal accounts is yours.

3. PHASE 3Email and files

   The mail skill with its three backends: Outlook classic through COM or Microsoft Graph with OAuth, and IMAP for Gmail and Titan, with approved sends. The mailbox knowledge skill and a 07:30 triage task. Then docx, xlsx and pptx skills, sharing through Tailscale Funnel, attache.ask from artifacts, and attache service install.

   Done wheneach morning the assistant files new mail in all three accounts, drafts the replies you need, sends the ones you approve in Slack, and starts at login.

   Built: pull request #35. Tested offline with fakes; the run against your real mail accounts, Tailscale and Task Scheduler is yours.

4. PHASE 4Cloud

   A Dockerfile with ATTACHE_HOME=/data, an owner login for the web page, a Fly.io guide (one machine, a volume, auto-stop off so the scheduler keeps running), an MCP client for the API backends, the codex-cli adapter.

   Done whenthe same package runs on a small cloud machine, with your folder synced by git.

Decided on 19 October

• Name: attache.
• Chat apps: Slack and Signal, both in phase 2, with Signal on your separate number. Telegram and WhatsApp are out of scope.
• Models: your Claude login (claude-cli) for your own chats, an API key (claude-api) for group chats.
• Email: Outlook through COM or Microsoft Graph with OAuth, chosen per account; Gmail and Titan over IMAP; all through the mail skill.
• Shared lists: members of a chat can tick off items on lists shared with it.

Deferred

• Cloud target. Nothing before phase 4 depends on it. Keeping everything in one folder under git, with Docker as the packaging, leaves Fly.io, Railway, a VPS and a home server all open.

To set up when we get there

• Phase 2, Slack: a workspace, and an app created from the manifest Attaché provides.
• Phase 2, Signal: Java 25 on this PC, then registering your separate number with a captcha and an SMS or voice code. Registering signs out any Signal app already using that number, so keep it for Attaché alone.
• Phase 3, Gmail: 2-Step Verification on, then an app password.
• Phase 3, Outlook through Graph (optional): a free Azure account for an Entra tenant, an app registration (desktop app, redirect http://localhost, delegated mail, calendar and tasks permissions), then mail.py login outlook.
• Phase 3, Titan: “Enable Titan on Other Apps” in webmail, and an Application Password if 2FA is on.

Checked on 19 October 2026. Line counts for nanoclaw come from its repository at three points in time. The nanobot line count is an estimate from its file tree.

• nanoclaw repository: README, CONTRIBUTING, docs
• nanoclaw PR #212: no web UI
• nanoclaw entity model: engage modes, roles
• OpenClaw repository
• OpenClaw group policy
• OpenClaw canvas
• nanobot repository
• nanobot commit replacing LiteLLM
• Claude Code headless mode
• Claude Code CLI reference
• Claude Agent SDK for Python
• Claude Code legal and compliance: subscription use
• Agent Skills specification
• OpenAI: migrate to Responses
• OpenAI deprecations
• Codex non-interactive mode
• Datadog: LiteLLM PyPI compromise
• OpenRouter Anthropic compatibility
• signal-cli
• signal-cli JSON-RPC
• Signal terms
• slack-bolt on PyPI
• Slack app manifests
• Slack rate limits for non-Marketplace apps
• Slack API terms
• Slack free plan limits
• Classic Outlook availability
• pywin32 on PyPI
• Outlook object model security behaviour
• Microsoft: unattended Office automation
• EWS retirement in Exchange Online (MC1227454)
• Outlook.com ends password sign-in for IMAP
• Gmail IMAP and SMTP
• Gmail IMAP extensions
• Google app passwords
• Gmail sending limits
• Titan IMAP and SMTP settings
• Titan application passwords
• Titan sending limits
• IMAPClient on PyPI
• Microsoft Entra: create a tenant
• Microsoft Entra: register an app
• Publisher verification
• Refresh token lifetimes
• Microsoft Graph permissions
• Microsoft Graph immutable IDs
• Microsoft Graph throttling limits
• msal on PyPI
• msal-extensions
• keyring on PyPI
• outlook-classic-mcp
• Robvred/outlook-mcp
• Slack Socket Mode
• Simon Willison: the lethal trifecta
• uv: running scripts, PEP 723
• uv: tools
• Tailscale Funnel
• Cloudflare quick tunnels
• Fly.io volumes