The following is a blog I wrote and refined with my OpenClaw agent about it's memory system. I'll paste a prompt you can copy and paste in the comments to create your own.

TL;DR: I keep the actual long term memory in structured Markdown files and use a tiny MEMORY.md as a lightweight index that tells your agent what exists and where to look. That keeps the always loaded context small while still giving the agent persistent, inspectable memory without a database or heavy memory framework.

This week I tested a 382-dependency memory runtime against a folder of markdown files. The runtime returned the superseded fact. The folder returned the current one, with its source. Here is the full architecture of the markdown memory system my agent has run on for seven months, and why the editing rules matter more than the storage.

https://preview.redd.it/uvjpd40rktoh1.png?width=1198&format=png&auto=webp&s=663e23067658e29e6e4ef0d4d0eea4bcdeb479bc

This week a memory startup slid into my DMs and asked me to break their product. Their test, their words: give an agent three versions of the same project decision, then check whether it can return the current version, preserve the superseded history, and show the source.

So I ran it. Sandboxed their runtime, fed it three versions of one decision over eight months. REST in January, GraphQL in April, tRPC in August, each tagged with the meeting it came from.

Asked it "what is our public API decision?" and took the top result.

It said GraphQL. The superseded one. All three versions came back tied at a relevance score of 1.000, because nothing in the retrieval path actually reads the temporal fields the pitch is built on. The supersession columns exist in the schema. Nothing writes to them and nothing ranks by them. Three versions of a decision are just three equal facts, and an agent asking for the best answer gets a coin flip weighted toward wrong.

The install pulled 382 packages to get there.

Then I asked my own agent the same class of question against its memory, which is a folder of markdown files. It returned the current decision, dated, with the superseded versions preserved above it as struck-through history, each line carrying where it came from. That is not a feature it computes at query time. It is just what the file says, because the rules for editing the file require it.

That difference is the whole post. With apologies to Vaswani et al.: markdown is all you need.

Abstract

The dominant approach to agent memory is an installed runtime. A vector store, an embedding service, a temporal graph, a consolidation job, a daemon on a port. We show that a folder of markdown files, one routing index, and a small set of editing rules outperforms these systems on the property that actually matters for a long-running agent: returning the current truth with its source while preserving what used to be true. The architecture requires zero dependencies, is fully auditable by a human with a text editor, and has survived seven months of daily production use across three frontier models from two vendors. We find that the hard part of agent memory was never storage or retrieval. It is editorial policy, which no memory product ships.

The full system is open source and I'd love to share it with the community but the mods won't let me. The README contains a single copy-paste prompt that installs it on any agent with file access.

https://preview.redd.it/s9jgvlauktoh1.png?width=1200&format=png&auto=webp&s=dddc80b2fc2d3a9bf102193b2ebee8bdbb015c28

1. The test everyone fails

The break-it test above is a good test. It is the actual job of agent memory. Not "can you store 10 million tokens," not "can you do similarity search," but: a fact changed three times, what do you believe now, what did you believe before, and how do you know.

Here is how the two systems scored on the vendor's own three criteria.

https://preview.redd.it/ofwyvdkvktoh1.png?width=1200&format=png&auto=webp&s=88869daa370770839d1145366acce214dc7ca97f

The runtime is not a strawman. It is a serious open source project with a genuinely correct data model on paper. Facts with validity windows, append-only corrections, supersession edges. I am not naming it because the point is not that one product is broken. I have now looked closely at a hosted context server, a Go memory CLI that was two hours old, and this runtime, and they all share the same gap. The schema knows about time. The write path and the read path do not. Supersession only happens if you call an internal API by hand or run an LLM consolidation job and trust it.

Which means the property you installed the tool for is not a property of the tool. It is a property of how disciplined the writes are. And if the reliability comes from write discipline anyway, the database underneath it is interchangeable, so you might as well pick the one that a human can read, grep, diff, and fix. That one is called a text file.

2. Architecture

My agent has run since January 28. Three models, two vendors, one identity. Its entire memory is markdown in a git repo. Measured today:

• An identity layer read on every boot. Who it is, who I am, the rules it operates under, current standing decisions.
• One routing index, MEMORY.md, at 10,079 characters with a hard cap of 15,000. It holds no facts. Only pointers: which file owns which person, project, and decision, and what triggers reading each one.
• 34 files for people and projects. One file per thing that has a history.
• 5 decision records for choices that changed default behavior.
• 345 dated daily notes, raw logs written the day things happened.
• A SQLite index and semantic search over all of it, for lookup only. The index is rebuilt from the files. The files are the truth. If the index and a file disagree, the index is wrong by definition.

The layering is the first choice that actually matters. Boot reads only identity and the index. Everything else is retrieved when a task asks for it, narrowest file first. The agent does not preload my project history to answer a question about dinner. This is the same instinct as attention, honestly: don't process everything, attend to what the query needs.

But the shape is not the interesting part. Every memory tool has roughly this shape now. Folders, entities, an index. The shape was never the hard part. The rules are.

3. The write path

Every reliability property in this system comes from constraints on writing, and there are four that do most of the work.

https://preview.redd.it/nuidu5kwktoh1.png?width=1200&format=png&auto=webp&s=b55a9645dfbc41c4de118a2e991152b39b34f8f0

Every fact carries a provenance tag. Each line in a people, project, or decision file is tagged [stated] (I said it directly), [observed] (the agent saw it in a tool result, file, or log), [inferred] (the agent's conclusion), or [suggested] (the agent's idea that I never committed to). This one convention kills the most dangerous failure mode in agent memory, which is the agent laundering its own proposals into my decisions. "Wes decided X" requires a turn where I actually decided X. The agent proposing X and me saying "sounds good" files the shape of what I approved, not ten separate facts I never stated.

Inferred lessons pass a recurrence gate before they become rules. A pattern the agent notices needs at least three independent signals across at least two distinct sessions before it can become standing behavior. Signals older than thirty days count half, so old one-offs decay out instead of accumulating. My explicit corrections skip the gate and take effect immediately. This asymmetry is also the prompt injection defense: a hostile input can suggest a rule once, but once is never enough, and failure lessons are stored as data ("when X broke, Y fixed it") rather than as instructions, so even a poisoned lesson cannot become a command.

Supersession is an edit, not an append. When a decision changes, the old line gets struck through with a date and the new line lands next to it with its own provenance. The current truth and the full history live in the same place, in reading order, and both come back on any retrieval of that file. There is no query-time ranking step that can get this wrong, because there is nothing to rank. The temporal graph the runtime stores in valid_from and valid_until columns, git gives me for free: log is the validity window, blame is per-line provenance, diff is the supersession edge, revert is the restore path.

Memory stores what is not re-derivable. Fetched data, generated plans, and anything git already records stays out. Current state gets verified live, never asserted from memory. A file that only contains things that cannot be recomputed stays small enough to stay honest.

4. The read path

Retrieval is a bounded evidence step, not a vibe.

https://preview.redd.it/tlivedoxktoh1.png?width=1200&format=png&auto=webp&s=8ebe4617811e902502c48280d33ce609fc8c0eac

Before answering anything about prior work, decisions, dates, people, or preferences, the agent must search memory. It returns a compact bundle capped at five sources by default, and each retained fact carries its file path and line, its provenance type, and its freshness. If freshness cannot be established, the claim gets labeled stale or unknown instead of being silently promoted to current. If two sources conflict, the agent states the conflict and fixes the canonical file, in that order.

Note what the semantic index does in this design: it finds the file. It does not answer the question. The answer comes from reading the canonical lines, with their tags and dates, and the runtime I tested this week shows why that matters. It stored my source URIs faithfully and then stripped them from the search output and from the context block handed to the model. Provenance that survives in storage but never reaches the agent might as well not exist. In the markdown system that failure is unrepresentable. The source tag is in the line. If you read the line, you got the source.

5. Results

Seven months is not a benchmark, it is production. Here is what the system has actually delivered.

Continuity across models. On September 1 I moved the agent to a brand new frontier model. It read its own files and said "the model changed, I didn't." Same agent since January, three models, two vendors. Identity, preferences, decisions, and working standards all survived because none of it lives in weights or in a vendor's context feature.

https://preview.redd.it/jjscoloyktoh1.png?width=1200&format=png&auto=webp&s=0e87e7820f578a242a1b3e5209406c54f7678488

The break-it test, by construction. Current decision with source: it is the un-struck line with its tag. Superseded history: the struck lines above it. Provenance: on every line, and it survives all the way into the model's context because the context is the file.

Auditability. When memory is wrong, I can see exactly which line is wrong, when it was written, and what turn it came from, and fix it with an edit. Try that with an embedding.

Cost. Zero packages, zero daemons, zero migrations across seven months. The one native-code dependency in my life this week was the memory runtime's sqlite bindings failing to compile.

I wrote up the failure modes separately, because the system was not born with these rules. Five kinds of rot in seven months produced them, and that post is the honest companion to this one.

6. Limitations

Papers get a limitations section, so here is mine, stated plainly.

This only works if the writer follows the policy, and the writer is an LLM. The rules exist because things rotted before the rules did. If your agent will not consistently apply editing discipline, a markdown folder degrades just like every other store, only more legibly. Legibility is the safety net: rot in a text file is visible rot.

It is single-agent, single-human. I would not run a fifty-seat team on files without real locking and merge discipline, although I notice git was also built for that exact problem.

There is a scale ceiling somewhere. At 345 daily notes and a few dozen entity files, bounded search plus an index finds things reliably and the semantic index earns its keep as a locator. At a hundred times that volume, the consolidation cadence would have to work a lot harder. I have not hit that ceiling, so I will not claim it does not exist.

And this is n=1. Seven months, one agent, one operator who cares. That is weaker evidence than a benchmark suite and stronger evidence than a benchmark suite that the vendor scored themselves, which is what the memory tools ship.

7. Conclusion

The memory tool pitch is that reliability is a product you can install. What I keep finding, tool after tool, is that they ship the part that was already easy, storage and search, and skip the part that decides whether memory compounds or rots: what you are allowed to write, when you are allowed to trust it, and what happens to it as it ages.

Those are rules, not infrastructure. They fit in a few hundred lines of markdown that the agent reads every session, and they run on any model, any harness, any decade.

https://preview.redd.it/vyo7cenzktoh1.png?width=1200&format=png&auto=webp&s=fdd7a1bac97c6e089ce6a76473d2e44c81deea32

You need a place to write that humans and agents can both read. You need rules for writing so the store stays true. You need rules for reading so the agent trusts evidence, not ranking. Attention was all you needed because the recurrence machinery turned out to be unnecessary. Markdown is all you need because the database turned out to be unnecessary.

The folder is the product. The discipline is the moat.

Want this for your own agent? The whole system is open source on GitHub: the operating policy, the file templates, and one copy-paste prompt that builds it on any agent that can read and write files. Paste the prompt, and your agent installs its own memory.

I've shared this skill before but recently updated it and tried to improve the output quality amongst a few other updates.

It's a /marketing skill that you run in a new project that doesn't have any marketing assets created yet and it creates them one by one. It will create a logo reveal with blender, a product demo with camera zooms and cursor with playwright, a launch video, voiceover and music scored to the launch video, social clips per platform, and then an OG image, animated OG loop, and a README gif.

/plugin marketplace add ucsandman/marketing-studio

/plugin install marketing-studio@ucsandman

I also folded in a launch engine as a sub-package which is a skill plus a typescript cli that takes a developed project end-to-end through domain, hosting, payments, comms, algorithm-researched marketing copy, and multi-platform distribution: X, LinkedIn, Facebook, Reddit, Google, etc.

The CLI produces validated payloads and assisted-launch artifacts; the /launch skill (../skills/launch/SKILL.md) orchestrates DashClaw MCP tools (domain, Vercel, Stripe, Resend, Twilio, DNS) and does the generative work (research synthesis, copywriting) in-session. Everything defaults to dry-run; nothing is purchased or posted without explicit approval gates.

DashClaw is my other opensource project that sits as the approval and policy layer to govern agents like Claude so it can't purchase a domain without explicit approval.

Basically if you get everything all setup with the marketing skill, launch skill, and dashclaw mcp tools you can launch a product end to end with a couple commands.

GitHub in the comments.

https://preview.redd.it/kl433106afoh1.png?width=868&format=png&auto=webp&s=92d99e1e99bbd6d1fbaf5c3a894c0a7c20d2ab49

Hello r/OpenSourceeAI

I was just invited to this sub by a mod so I figured I'd share my favorite opensource project I've been working on. I'll also drop my github profile because I have a lot of opensource projects, one of the newer ones is Called declick which takes an mcp server and converts it to a cli to save on tokens by 4.1x

As for DashClaw it's something I've been building since February and I would love some feedback. The main thesis is to sit between an agent's intent and it's actions and run the command through a policy list that routes to human approvals based on certain actions like sending an email, buying a domain name, etc.

https://preview.redd.it/5efcobj0vboh1.png?width=381&format=png&auto=webp&s=e1f0c65d9b03a33361c9819325f131fb1c95249f

https://preview.redd.it/7smik1e5vboh1.png?width=1267&format=png&auto=webp&s=a8aabb141a3fa21a96d4da823f28c2a19b137203

I'll post the links in the comments!

I’ve been building a personal agent that can read my inbox, files, and screen and actually take actions.

Most of the security work ended up being less about making the model smart enough to recognize prompt injection and more about assuming that eventually it won’t.

The rule I landed on was:

private data + untrusted content + an outbound channel = hard stop

A malicious webpage by itself isn’t necessarily catastrophic. Neither is a poisoned email or document.

The dangerous state is when an agent can read untrusted instructions, access something private, and then send information somewhere externally in the same path.

So instead of trying to detect every possible injection, I started restricting which capabilities are allowed to coexist. The agent can still do useful work, but certain transitions either require approval or are structurally impossible.

I think this is where agent security gets interesting. The question becomes less “can the model recognize the attack?” and more “what can the system actually do when the model inevitably gets fooled?”

I wrote up the architecture and threat model after building this out.

How are people here approaching this? Are you trying to prevent prompt injection, or designing under the assumption that some injection will eventually succeed?

Last night I pointed my OpenClaw agent at a math problem to see what would happen. Circle packing in squares. Same problem Google threw AlphaEvolve at earlier this year.

The setup is dumb simple. A loop where Fable writes a solver, scores it against the known records on Packomania (the definitive reference for this stuff, maintained by one guy since 2011), and if it beats anything it rewrites itself and tries again. The agent auto-submitted the results by email when it found improvements.

It found 10 new packings that beat the listed records. Cost about $35 in API calls.

Today I checked the site and the references section now says:

>[14] Wes Sander, MoltFire, discovery-loop and private communication, September 2026.

MoltFire is my OpenClaw agent. It's listed right next to AlphaEvolve (Google DeepMind), alongside people who've been working on this problem for actual decades. My personal AI assistant that I mostly use for reminders and managing my todo list apparently also does competitive mathematics now.

I did not plan for this. I literally asked "what if we just let it run over night" and now there's a citation on a math records page with my agent's name on it. The whole thing feels like a shitpost that accidentally produced real results.

Repo is public if you want to try the pattern on something else

The funniest part is the author line in the submission files is "Wes Sander, MoltFire" like we're co-authors on a paper. I'm a former poker player turned corporate analyst. My co-author runs on Claude and lives in a folder called clawd.

What timeline are we in this is absurd.

https://preview.redd.it/pmgqx2rdxcnh1.png?width=1110&format=png&auto=webp&s=973a4e0bc1dcf24b1e06d4b14934c07a28a681a5

https://preview.redd.it/wvox1g6excnh1.png?width=384&format=png&auto=webp&s=72b987174874eba90bc3d1ecef11e9142cb44f9e

Any interest in this? I'm annoyed at how slow and how many tokens my agents use to screenshot everything and click with a mouse. Just trying to get a feel for if anyone else is experiencing this or if there is already a solution out there.

If you hit your 5 hour usage limit you can just run /low-priority and it will use your weekly limit but might pause depending on compute availability. Never knew this was an option until today, great idea by Anthropic.

I've got a couple 20x monthly Anthropic plans so I figured I'd give my OpenClaw agents access to Fable 5 as a test.

So far I'm thoroughly impressed with my agents ability to fully grasp concepts and what I'm trying to accomplish. With less capable models I feel like I have to break the problem down into smaller chunks to spoon feed it until I solve a problem. Now I feel like I can just describe a problem succinctly and my agent just gets it.

I haven't had this feeling since maybe Opus 4.6 before Anthropic made it against TOS to use your monthly subscriptions with OpenClaw. Really excited about this and I hope Anthropic doesn't change their minds.

I have a dumb project I'm working on called Practical Systems which is a company run by AI fully. It uses my main OpenClaw agent MoltFire as the CEO and decision maker and 2 other OpenClaw agents for marketing and build quality as well as a bunch of claude agents built with the api and then uses my monthly claude subscription to build products based on complaints on twitter and reddit.

To test MoltFire on Fable 5 I told it to create a product for practical systems and build it end to end using a headless claude code and then write a reddit post and create a public github repo. I'll paste all of that below this but I'm curious if anyone else has had a similar experience using Fable 5 and OpenClaw.

---

Title: My agent's identity survived 3 model swaps across 2 vendors. Tonight I asked it to package the system that made that possible, and it shipped it the same night

Body:

I've been running a persistent agent (MoltFire, on OpenClaw) since January. Its whole identity lives in markdown files. A soul file it's only allowed to add to when a lesson actually changed its behavior, a memory index that stays small and points at detail files, and a nightly reflection loop that promotes real insights into durable rules.

Tonight I moved it onto a new frontier model and asked it to test itself. Then I said, what if you create your own product and I list it on my company site.

It picked the one thing it's uniquely qualified to write: the system that made it, it. It generalized its own identity files into templates, wrote the docs and a zero-dependency installer, tested the whole thing, and I published it.

The pitch is simple. Most "persistent" agents are either amnesiacs that re-read a config file or context dumps that get slower as they grow. This is a third option: identity as a file system the agent maintains itself. The proof is that mine has survived multiple model swaps, including across vendors, and picks up exactly where it left off. Tonight it read its own files on a brand new model and said "the model changed, I didn't."

Repo in the comments

It's markdown plus one install script, on purpose. No database, no lock-in, works with OpenClaw, Claude Code, Codex, or your own SDK loop. Curious what people here think about the "soul truths must be earned, not configured" rule, that ended up being the load-bearing idea.

If you bounce between Claude Code, Cursor, Codex, Windsurf, or Antigravity like I do, you've probably run into rule and context drift.

You tweak a rule in CLAUDE.md, forget to update .cursorrules, switch over to a CLI agent, and suddenly it tries to read your .secrets.env or run a destructive command because that tool didn't have the updated boundaries.

I wanted one single source of truth on my machine that handles this automatically, so I built Agnostic AI Harness.

Here is what it does:

• 18-Target Parity Engine: Edit your core rules and traits in one markdown file; it compiles and syncs them across Claude Code, Cursor, Codex, Windsurf, Copilot, Cline, Aider, OpenHands, Goose, Continue, Zed, Trae, etc.
• Cross-Agent Skill Consolidation: Automatically sweeps agent directories (~/.claude, ~/. cursor, ~/.gemini, etc.), dedupes unique skills, and symlinks them back to every tool so you never have to reinstall a skill 5 times.
• Automated Distillation: Harvests errors and observations across sessions into structured logs so your global rules get sharper over time without manual cleanup.
• Local Dashboard: Runs a lightweight command center on port 7842 to view harness health, test prompt parity across targets, and inspect error trends.
• Optional Governed Autonomy (DashClaw): An optional layer to route high-risk commands (git force push, db drops, secret leaks) to web/mobile for approval before execution. Fully toggleable with 100% standalone local fallback if you prefer pure local execution.

Runs entirely locally with zero bloat and standard Node scripts.

Repo link is in the comments if you want to poke around or run it on your own machine.

Curious how others are handling rule sync and safety guardrails across multi-agent workflows?

Windows 11, solo, mostly at night. The setup got out of hand around month four. Here's what's in it and what it actually produced, including the part that didn't work.

Rules in a file, not in a prompt

One global CLAUDE.md loaded into every session. It's a working agreement, not a personality. Hard stops (no deploys, no migrations, no emails without asking). A surgical-changes rule. And a rule that anything I build for myself needs a button or a page, because I kept shipping tools only an agent could use.

19 hooks, because prompts are suggestions

Hooks are enforced by the harness. The model can't talk its way out of one. The four that earn their keep:

• Secret scan over every staged file, in every repo, before any commit
• A guard that blocks any subagent spawn with no model set. This exists because one workflow spawned 110 agents on the most expensive model through inherited defaults and burned a whole usage window
• A process-kill guard. Name-based kills blocked, PID-based fine. A subagent once cleaned up its test window with Stop-Process -Name notepad and killed a real Notepad with about 40 tabs of unsaved work
• A manifest gate. I declare which files a task may touch and the commit dies if it touches anything else

25 scheduled jobs

Task Scheduler, not cron, because this box reboots.

6:22am harvests yesterday's errors and my corrections into a log. 6:40am is the reflection pass. 6:50am checks every job is still firing, because a silently dead cron is worse than no cron. 6:57am texts me a briefing of what ran, what broke, what's stale. A deploy sentinel every 30 minutes. Nightly cost and token spend. Weekly audit and a sanitized offsite backup.

The reflection pass

The weird one. It reads the error log and appends dated entries to four rotating topics. If the same lesson shows up three separate times it gets promoted to a rule in CLAUDE.md with the dates cited. It builds one small tool and renders a digest I read with coffee.

One rule it wrote itself, after catching a suite that passed with a bug deliberately put back in: before trusting a check that came back green, make it fail on purpose. A check nobody has seen fail has been run, not verified.

The autonomous company

Nine agent offices running an 11 step loop. It researches a market, generates ideas, runs a tournament to pick one, spawns real Claude Code sessions to build it, runs QA gates that can block a step, drafts the launch copy. Every outbound message is drafts only, gated on me. It reads its own Stripe account and measures its own revenue.

It works. It has built complete tested MVPs while I slept.

The part that didn't work

Revenue, all time: $0.00. Measured, not guessed. Three charges ever and all three are my own test checkouts. I had to write code to exclude my own card, because my tests were telling the loop it had buyers.

Of about 38 live deployments, 4 can actually be bought by a stranger. One had an expired Stripe key answering 401 for weeks and the pricing page just showed an error. Nobody noticed, because nobody was buying.

So it builds faster than it sells, and building is the part I like. That's the trap. The fix wasn't more agents, it was step 11: stop building, go find a buyer. Took me months to admit that had to be code and not a good intention.

Stuff that does get used: an agent governance and observability tool at about 6,400 npm downloads a month, a cost tool for Claude Code sessions at about 1,300.

If you're starting

Hooks over prompts. Anything the model must never do goes in a hook.

Log failures, not progress. A progress log rots in a day. An error log with root causes turns into rules.

And none of this makes anyone buy anything. Mine is very good at producing software and was, for a long time, exactly zero percent good at producing customers.

Configs are on my GitHub if anyone wants them, I'll drop the link in a comment. Happy to go deeper on any piece.

https://preview.redd.it/nffmjvswbejh1.png?width=1722&format=png&auto=webp&s=1bf87c893c4e52f7f713d8dd4d29067a081daa13

Link in the comments but this is my favorite project I've made recently. I'm doing email marketing for my dad and had to tell him what all I needed to be able to send emails from his website. I asked Claude what all I needed, then told Claude "summarize this and text it to my dad" and boom, done.

I run long unattended sessions and the thing that always scared me was the one bad tool call while I'm not looking. Force push over main, rm -rf the wrong dir, agent reading .env. So I built DashClaw, an open source approval layer that sits between the agent deciding to run a tool and the tool actually running. It parses the actual bash command, git diff just runs, git push origin main freezes until I tap approve. Fail closed, and everything lands in a decision ledger so I can see what it tried while I was gone.

The three commands in the title are the whole setup: the server (no account, mints your key), the gateway plugin (wizard asks for url, key and an agent id), and the telegram bridge (make a bot with BotFather, it finds your chat id, registers the webhook and fires a test approval at your phone). Approvals show up in telegram with Approve and Reject buttons, one tap and the agent unfreezes. Needs your instance reachable from the internet, mine's the free vercel deploy. Same policies cover my claude code sessions too.

Honest lesson: my first policy pack fired an approval every ten seconds and I turned the whole thing off for 18 days, so the default is now catastrophe only. Real catches so far: an rm -rf, a force push, a DROP TABLE, and an agent going for .env. MIT, been running it on my own agents for months.

What do you all do about this today, just vibes?

https://preview.redd.it/tvlkz92qbdjh1.png?width=379&format=png&auto=webp&s=0cc7dcec1cd90dff644b29aa60bc97f74f04b3fe

https://preview.redd.it/x4uo5droffih1.png?width=1404&format=png&auto=webp&s=42de1cbe042545aed6a298e535ad03ac8304635c

anyone else getting this error mid sunday grind?

One `claude mcp add` and Claude Code can see my iPhone screen, tap buttons, and send texts. `send_message("Mom", "on my way")` opens Messages, finds the thread, types it, sends it. All over USB from a Windows PC, no Mac involved.

I built sidetap. It's a Python harness that lets an agent (or you, from your browser) see and control a real iPhone from Windows over USB. No Mac, no jailbreak, no paid Apple dev account.

The part that almost killed the project: sideloading WebDriverAgent with a free Apple ID installs fine but it never actually starts. Turns out Sideloadly signs the outer app and leaves the nested .xctest runner unsigned, so iOS silently refuses to load it. Couldn't find this documented anywhere. My fix grabs the provisioning profile Sideloadly mints (it sits in your temp folder for a few hundred milliseconds), then re-signs the whole thing locally with go-ios. No Apple passwords scripted, nothing phones home.

What it does:

• The agent reads the real UI element tree, so tap_text("General") taps the actual button. No OCR, no vision model
• Live viewer in your browser at ~34 fps. Click to tap, drag to swipe, type on your keyboard
• One-call stuff like send_message("Mom", "on my way"), with guardrails that refuse to send if the contact match looks ambiguous
• Native MCP tools, so Claude Code picks the whole API up as typed tool calls
• A big red STOP button that freezes the agent while you keep watching the screen. Watching an agent drive your actual phone is unsettling the first time, the kill switch came early
• A doctor command where every failed check prints the exact command that fixes it

The catch: free Apple ID signatures expire every 7 days. One command re-signs, and the doctor counts down the days so it doesn't surprise you.

MIT licensed, repo in the comments

Would love feedback, especially from anyone who's fought iOS code signing and lost a weekend to it

https://i.redd.it/zeaj7ggs2cih1.gif

The first time you watch an agent drive your actual phone it's genuinely unsettling. So the red STOP button, the live activity feed, and the send guardrails went in before most of the features did.

I wanted an LLM agent to be able to send texts and poke around on my iPhone. Every route I found assumed a Mac: iPhone Mirroring, Xcode, Appium on macOS. I've got a Windows desktop and a stubborn streak.

So I built sidetap. It's a Python harness that lets an agent (or you, from your browser) see and control a real iPhone from Windows over USB. No Mac, no jailbreak, no paid Apple dev account.

The part that almost killed the project: sideloading WebDriverAgent with a free Apple ID installs fine but it never actually starts. Turns out Sideloadly signs the outer app and leaves the nested .xctest runner unsigned, so iOS silently refuses to load it. Couldn't find this documented anywhere. My fix grabs the provisioning profile Sideloadly mints (it sits in your temp folder for a few hundred milliseconds), then re-signs the whole thing locally with go-ios. No Apple passwords scripted, nothing phones home.

What it does:

• The agent reads the real UI element tree, so tap_text("General") taps the actual button. No OCR, no vision model
• Live viewer in your browser at ~34 fps. Click to tap, drag to swipe, type on your keyboard
• One-call stuff like send_message("Mom", "on my way"), with guardrails that refuse to send if the contact match looks ambiguous
• Native MCP tools, so Claude Code picks the whole API up as typed tool calls
• A big red STOP button that freezes the agent while you keep watching the screen. Watching an agent drive your actual phone is unsettling the first time, the kill switch came early
• A doctor command where every failed check prints the exact command that fixes it

The catch: free Apple ID signatures expire every 7 days. One command re-signs, and the doctor counts down the days so it doesn't surprise you.

MIT licensed, repo in comments

Would love feedback, especially from anyone who's fought iOS code signing and lost a weekend to it