# John Muthee

> John Muthee is a full-stack engineer in Nairobi building AI agents, agent infrastructure and production web platforms with Laravel, TypeScript, Python and React.

Full-stack engineer in Nairobi. I build agentic AI systems, the memory, orchestration and testing tools that keep them honest, and the web and mobile products they run inside. Open to freelance and contract work. Based in Nairobi, Kenya. Contact: johnmuthee547@gmail.com.

## Pages

- [Overview](https://john.muthee.mutexai.net): profile, pinned projects, contribution activity and latest writing
- [Projects](https://john.muthee.mutexai.net/projects): open-source agent infrastructure, products and platforms
- [Writing](https://john.muthee.mutexai.net/writing): articles and notes
- [Newsletter](https://john.muthee.mutexai.net/newsletter): Build notes archive and signup
- [CV](https://john.muthee.mutexai.net/cv): experience, education and skills
- [Contact](https://john.muthee.mutexai.net/contact): hiring and project enquiries

## Projects

- [agent-memory-server](https://john.muthee.mutexai.net/projects/agent-memory-server): Self-hosted, git-backed memory any AI agent can plug into (source: https://github.com/mutheejj/agent-memory-server)
- [worktree-orchestrator](https://john.muthee.mutexai.net/projects/worktree-orchestrator): Parallel coding agents in isolated git worktrees, merged deterministically (source: https://github.com/mutheejj/worktree-orchestrator)
- [mcp-african-markets](https://john.muthee.mutexai.net/projects/mcp-african-markets): MCP servers for African fintech: M-Pesa payments, reconciliation, sandbox by default (source: https://github.com/mutheejj/mcp-african-markets)
- [agent-test-harness](https://john.muthee.mutexai.net/projects/agent-test-harness): Chaos testing for AI agents: inject failing tools, grade the recovery (source: https://github.com/mutheejj/agent-test-harness)
- [Andor](https://john.muthee.mutexai.net/projects/andor): An AI coding agent that lives inside VS Code (source: https://github.com/mutheejj/andor)
- [AjiraWorks](https://john.muthee.mutexai.net/projects/ajiraworks): A work and gig-economy platform connecting talent to opportunity
- [cron-for-agents](https://john.muthee.mutexai.net/projects/cron-for-agents): Scheduled agent jobs with dedup, watermarks and delivery (source: https://github.com/mutheejj/cron-for-agents)
- [repo-doctor](https://john.muthee.mutexai.net/projects/repo-doctor): Clone a repo, run its tests, get a PR-ready diagnosis (source: https://github.com/mutheejj/repo-doctor)
- [HR System](https://john.muthee.mutexai.net/projects/hr-system): Payroll, leave, performance and the full employee lifecycle
- [AlfaTalent](https://john.muthee.mutexai.net/projects/alfatalent): A talent management and development platform
- [Mutex AI](https://john.muthee.mutexai.net/projects/mutex-ai): An independent AI engineering studio, with an on-site Claude agent
- [This portfolio](https://john.muthee.mutexai.net/projects/this-portfolio): john.mas.codes, with an MCP server so agents can draft posts here
- [ALX simple_shell and Monty interpreter](https://john.muthee.mutexai.net/projects/simple-shell-and-monty): A Unix shell and a bytecode interpreter, written in C (source: https://github.com/mutheejj/simple_shell)
- [AirBnB clone: the console](https://john.muthee.mutexai.net/projects/airbnb-clone): A command-line interpreter for managing AirBnB-style objects (source: https://github.com/mutheejj/AirBnB_clone)

## Writing

- [Build notes #4: this portfolio is live, and I can no longer write my own posts](https://john.muthee.mutexai.net/newsletter/build-notes-4-this-portfolio-is-live): The site you are reading this on just shipped. It has its own MCP server, which means an agent can draft posts here directly, review queue included. Plus agent-memory-server went open source.
- [Git-backed memory for AI agents: why files beat a vector database](https://john.muthee.mutexai.net/writing/git-backed-memory-for-ai-agents): I run several coding agents that share one durable memory made of markdown, JSON and git commits. Here is why plain files beat a vector store, and how sessions, leases and decisions work.
- [Why the assistant's tools default to read-only](https://john.muthee.mutexai.net/writing/why-the-assistants-tools-default-to-read-only): A short note on a naming habit from the mutexai.net assistant. Read-only tools get plain verbs. Anything that writes gets a verb that says so, on purpose, so a reviewer never has to guess.
- [Running AI coding agents in parallel with git worktrees](https://john.muthee.mutexai.net/writing/running-ai-agents-in-parallel-with-git-worktrees): Three agents on one checkout means trampled files and lost work. Giving each task its own git worktree, its own model and a deterministic merge step fixed that for me.
- [Chaos testing AI agents: inject failing tools, grade the recovery](https://john.muthee.mutexai.net/writing/chaos-testing-ai-agents): Happy-path demos tell you nothing about what an agent does when a tool returns a 500. I test agents like distributed systems: inject faults on purpose and score recovery against bluffing.
- [repo-doctor: diagnosing failing test suites with an agent](https://john.muthee.mutexai.net/writing/repo-doctor-diagnosing-failing-test-suites): Clone, install, run the tests, then separate real regressions from environmental noise. Why I built repo-doctor as a deterministic pipeline first and an agent second.
- [A cron job's watermark file is not optional](https://john.muthee.mutexai.net/writing/a-cron-jobs-watermark-file-is-not-optional): A short note from building cron-for-agents. The first version kept its watermark in memory, a restart erased it, and an agent reprocessed a week of old data. State belongs on disk.
- [Scheduled agent jobs: why cron needs dedup and watermarks](https://john.muthee.mutexai.net/writing/scheduled-agent-jobs-dedup-and-watermarks): Plain cron runs your agent on time, then wastes tokens reprocessing old data and spams you with identical summaries. Watermarks and content-hash dedup fix both.
- [Build notes #3: cron jobs, sandbox payments, and a test harness](https://john.muthee.mutexai.net/newsletter/build-notes-3-cron-jobs-sandbox-payments-and-a-test-harness): Two months of unglamorous infrastructure. A cron tool that does not spam duplicate summaries, sandbox M-Pesa tools for agents, and the start of a proper way to test how agents fail.
- [M-Pesa Daraja over MCP: designing payment tools for AI agents](https://john.muthee.mutexai.net/writing/m-pesa-daraja-over-mcp): What MCP is, why payments are the hardest tools to give an agent, and how I am designing Daraja tools around sandbox defaults, idempotency keys, reconciliation and human approval.
- [Git worktrees: clean up the ones you forget](https://john.muthee.mutexai.net/writing/git-worktrees-clean-up-the-ones-you-forget): Worktrees do not disappear when an agent's task ends. A short note on the cleanup step I almost skipped while building worktree-orchestrator, and the disk space and confusion it saves.
- [Building an on-site Claude agent in Laravel without an SDK](https://john.muthee.mutexai.net/writing/on-site-claude-agent-in-laravel-without-an-sdk): How I built the assistant on mutexai.net with Laravel's HTTP client: a bounded tool-use loop, a daily spend cap, a local fallback that always answers, and a human-reviewed learning queue.
- [Build notes #2: an assistant that knows when to stop](https://john.muthee.mutexai.net/newsletter/build-notes-2-an-assistant-that-knows-when-to-stop): The on-site assistant for my studio is live, with a spend cap, a fallback and a human-reviewed learning queue. Plus what building Andor taught me about agent completion states.
- [Designing tools that AI agents actually use well](https://john.muthee.mutexai.net/writing/designing-tools-that-agents-use-well): Most agent failures I debug are tool design failures. Names, schemas, descriptions and error messages decide whether a model calls the right tool with the right input.
- [The Daraja sandbox lies about idempotency](https://john.muthee.mutexai.net/writing/daraja-sandbox-lies-about-idempotency): A quick note on M-Pesa Daraja's sandbox. It will silently accept a duplicate STK push request that production would reject, so idempotency keys need testing against real behaviour, not just the docs.
- [What writing a Unix shell and a Monty interpreter in C taught me](https://john.muthee.mutexai.net/writing/what-writing-a-shell-in-c-taught-me): Before I built agents I built a shell, a printf and a bytecode interpreter in C during the ALX programme. The lessons still shape how I design software today.
- [Build notes #1: why I'm writing this, and what's on the bench](https://john.muthee.mutexai.net/newsletter/build-notes-1-why-im-writing-this): The first issue of Build notes. What this newsletter is, what it is not, and what I am building right now: an AI coding agent for VS Code and my studio's website.

## Optional

- [Full text of every post and the CV](https://john.muthee.mutexai.net/llms-full.txt)
- [RSS](https://john.muthee.mutexai.net/feed.xml)