Same model as opencode, same endpoint, same prices — octomind solved 24/25 to its 19/25, at half the cost. Open-source agent runtime: one binary, any model, runs unattended in CI. Apache 2.0.
A coding agent for the terminal on your own API key (OpenRouter, Anthropic, OpenAI…). Describe the steps; it runs them as a checked, resumable workflow. Free.
HomeShed is a self-hosted Model Context Protocol tool server. Add it to your
AI assistant and it can check your containers, work with git, remember what it learned across sessions, spot bugs
it has seen before, and solve logic problems: 173 tools behind one endpoint that you run and control.
New in 0.7.0: one-click sign-in for Claude.ai and other MCP apps
Add HomeShed to your chat app in one step: paste the address, sign in, approve the 6-digit code on your Control
Panel. No key to copy and paste. Every app gets its own access level, limits and an off switch, and your memory,
tools and keys stay on your own machine. It's the standard MCP sign-in (OAuth 2.1 with PKCE), so any MCP app that
supports sign-in can connect; tested with Claude's custom connectors. Free, in the open-source core.
Set it up
Why people use it
Free and open source (Apache-2.0). One install, 173 tools, no account, no GPU.
New in 0.7.1
Text to speech. Turn text into spoken MP3s with Google's Chirp 3 HD voices, made for audiobooks. It stays inside
Google's free 1 million characters a month unless you allow more (guide: Control Panel > Guide > Google text to
speech).
Trusted browsers for sign-in. Approve a chat app once and tick "Trust this app on the browser that asked": its
later sign-ins from that browser go straight through for 90 days. Remove any of them on the API page.
Checked code work (Pro). In HomeShed Pro's to-do list, an item marked for checking is done only when a different session verifies the commit;
a check from the builder's own model family also needs a second opinion from another family.
A faster Control Panel. Each page loads the first time you open it, so the panel opens quicker and does less
while idle.
New in 0.7.0
One-click sign-in for Claude.ai and other MCP apps. Paste the address, sign in, approve the 6-digit code on
your Control Panel: no key to copy. Every app gets only the tools you choose, its own limits and an off switch. Your
HomeShed, its memory and its tools, now reach your chat apps, not just the ones on your computer. It's the standard
MCP sign-in, tested with Claude's custom connectors (how). HomeShed Pro
adds per-app tool sets, a savings report and approve-in-chat cards on top.
Cheaper on every turn: the front door. Instead of loading 160+ tool descriptions, an app sees five tools that
find and run all the others. Replies can be cut to just the fields you need, or kept on the server and read a page
at a time, and pictures arrive as real images, not text. Fewer tokens, and small models pick the right tool more
often. Switch it per app on the Control Panel's API access page.
Choose when Claude Code compacts. One setting sets how full a chat gets before Claude Code summarises it.
See what happened to a request.approvals.status tells your AI whether something it asked for was approved,
declined or is still waiting, and who decided.
Everything else
Memory that carries across sessions. Your AI remembers facts, decisions and fixes between conversations and
across projects. It's built in, with nothing extra to run. Facts are kept by category and recalled by relevance
to the task in hand, and in Claude Code each project gets its own memory automatically.
Finds the API keys your AI has already seen. Claude Code keeps every conversation on disk as plain text,
including any key that was pasted or printed. HomeShed checks those files and tells you which kinds of key are
there, where, and where to rotate them, without showing the keys themselves.
Reasoning where language models slip. A logic and constraint solver (Z3) handles the puzzles models get
wrong, big tasks break into steps, and a router says when a task needs a frontier model and when a smaller one
will do.
Your model first, the cloud when you choose. Routine work like drafts and summaries can go to a model you
run (Ollama, llama.cpp, LM Studio) or to cloud keys you bring. HomeShed doesn't include a model or need a GPU.
Ready-to-publish checks for your own projects. What a professional repository needs, private details and
secrets caught before they go public, docs checked against the code, and a progress score. They're the checks
used to prepare this release.
Mistakes that stay fixed. Your AI logs corrections and broken rules as observations, repeats get flagged, and a
known-bugs list answers "has this error been seen before?"
Checks before your AI acts. Rule packs check each command and file write before Claude Code runs it, and stop
risky ones with the reason and what to do instead. Anyone can write their own in a few lines of JSON
(how). Or skip the trial and error: HomeShed Pro's five packs are already
written, tested on real sessions and kept up to date, and each one is a single install.
A Control Panel, if you want one. An optional web page on your own machine shows what's running and what it has
saved you, with a switch for every tool and a key for every app. Add it any time; HomeShed never needs it.
One endpoint, you stay in control. Every app gets its own key, tool list and rate limit, and every change to
them is logged. Tools that act on your machines start off, and keys sit in an encrypted vault that's never shown
to the AI.
Your homelab at a glance. If you run Proxmox, the Control Panel's Proxmox tab and proxmox.health show every
node, VM and container, and send you an alarm when something breaks and again when it recovers. A Terminal tab
(off until you switch it on) gives you SSH to your own machines in the browser.
Spend you can cap. Every app gets a daily dollar cap for paid models and images. At the cap its paid calls stop
and everything free keeps working.
Never lose your place (Pro). Before Claude Code compacts a long session, HomeShed Pro saves a note
of what you were doing and puts it back straight after. More.
Try it: things to ask
Once HomeShed is added, just ask your AI. A few favourites:
Ask your AI
What happens
"Have I ever pasted an API key into Claude Code?"
secrets.transcript_scan checks your saved sessions and lists each key's kind, where it is and where to rotate it, without ever showing the key
"Remember that we deploy from the release branch", then next week: "where do we deploy from?"
memory.remember_fact saves it; memory.recall_relevant finds it in a later session
"Seen this error before?"
bugs.find checks your known-bugs list (and Pro's feed, if you have it) for the cause and fix
"Ann, Bob and Cat sit in a row. Ann isn't next to Bob, and Bob isn't on the left. Who sits where?"
reasoning.solve hands the logic to the Z3 solver, so the answer is proven, not guessed
"Is this repo ready to go public?"
repo.readiness scores it with one fix per gap; repo.leak_scan finds private details and secrets first
"Is my site leaking anything?"
network.exposure_check tries the paths attackers try first (admin pages, /.env, /.git) on your own public site
"How's the Proxmox cluster?"
proxmox.health: quorum, each node's CPU, RAM and disk, what's running, and any alarm active now
"How many stars and downloads did my project get?"
repo.stats: stars, forks, release and PyPI downloads, plus views and referrers with a GitHub token
"What did my apps spend on AI today?"
spend.today: each app's spend against the daily cap you set
"Find me a tool to check SSL certificates"
tools.find lists the best matches in plain words, without loading every tool
"Was my email to the team approved yet?"
approvals.status: waiting, approved or declined, and who decided
"Read chapter one aloud as an MP3"
tts.synthesize speaks it with a Google Chirp 3 HD voice, inside the free monthly allowance, once you've set it up
"Which container keeps restarting?"
docker.container.list and docker.container.logs, once you switch Docker on
Windows: the simple way
New to all this? You only need the Claude desktop app. Claude does the installing for you, and you never need
to type a command. Takes about 10 minutes.
Before you start: Claude's Code tab needs a paid Claude plan (Pro or higher). On the free plan, use
Install below instead.
Get the Claude app. Download it from claude.com/download, install it, open it
and sign in. Using the app already? Skip this step.
Make a folder for HomeShed. Open File Explorer, go to Documents, right-click an empty space, choose
New > Folder and call it HomeShed.
Switch Claude to Code. In the Claude app, click the Code button, the </> icon at the top right (the
Chat button beside it takes you back). This is where Claude can install things on your PC. Everything below
happens in the Code view: your chats won't show there, and this one won't show under Chat. That's normal.
Point it at your folder. Under the message box, click the first box and pick Local. Click the box next
to it, choose Open folder… and pick the HomeShed folder you made.
Ask Claude to install HomeShed. Copy this, paste it into the message box and press Enter:
Install HomeShed on this Windows PC by following "For AI agents: install on Windows" in
https://github.com/keefng8/homeshed-mcp, then start the Control Panel and give me its link.
Claude asks before running each command. Read what it's going to run, then click Allow. The first download
takes a minute or two. If Claude asks you to restart the app, quit it fully (right-click the Claude icon by the
clock and choose Quit), open it again, open the HomeShed folder in the Code view, and say "carry on".
Sign in to your Control Panel. It opens in your browser at http://127.0.0.1:9090. Claude tells you where to
find your first-time password. Sign in, then change the password in Settings and keep it somewhere safe.
Try it. Start a new session in the Code view (so Claude loads HomeShed), then ask:
"What tools do you have from homeshed-mcp?"
Next time, the Control Panel starts by itself when you sign in to Windows. Bookmark http://127.0.0.1:9090.
Already use Claude Code in a terminal? You can type the same request into claude instead. To follow along in
the Claude app too, type /remote-control and choose Enable Remote Control: the session then shows in the app's
Code view.
You're installing HomeShed for someone who may be new to all this. Run each step in PowerShell, in the folder they
opened. Say what each command does before you run it. Never print or save their keys or tokens.
uv, which runs HomeShed. If uvx --version fails, install it with
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex", then make it usable in this shell:
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path".
Add HomeShed to Claude Code. If the claude command works, run
claude mcp add -s user homeshed-mcp -- uvx homeshed-mcp. If it doesn't (common in the Claude app's Code view), write a .mcp.json file in this folder containing
{"mcpServers": {"homeshed-mcp": {"command": "uvx", "args": ["homeshed-mcp"]}}}. Then run uvx homeshed-mcp doctor
and fix anything it reports. If you installed uv in step 1, the app can't find uvx until it restarts: finish
step 3 first, then ask the person to quit the app fully and open it again (the app will ask them to trust this
folder's .mcp.json; they should accept).
The Control Panel. Run uvx --from "homeshed-mcp[panel]" homeshed-mcp panel --start --at-sign-in. It sets
HomeShed up the first time (its settings and token go in the data folder; never show them), starts HomeShed and
the panel in the background, opens http://127.0.0.1:9090, and starts them again whenever the person signs in to
Windows. On the first start it prints where the sign-in password file is: tell the person that path, not the
password. panel --stop stops both; panel --not-at-sign-in removes the sign-in start.
Tell them to start a new session so the HomeShed tools load, and to try "What tools do you have from
homeshed-mcp?" If anything fails, run uvx homeshed-mcp doctor and follow what it says.
Install
Install only from the official sources: PyPI homeshed-mcp, ghcr.io/keefng8/homeshed-mcp,
github.com/keefng8/homeshed-mcp and the MCP Registry io.github.keefng8/homeshed-mcp. Look-alikes may carry malware (more).
A real run, from setup to the first answers:
Three steps. No accounts, no keys, no GPU.
1. Install uv (the tool that runs homeshed-mcp; once per computer). Open a terminal (Windows: press Start, type
PowerShell, press Enter; macOS: open Terminal) and paste:
Then close the terminal and open a new one, so it can find uv. uvx --version prints a version number when it's
ready.
2. Add it to your AI app. For Claude Code (already installed), one command finds a local model if you run one,
lists the optional tool groups (the ones it finds are ticked: press Enter to keep them), then asks before adding
HomeShed (answer Y):
uvx homeshed-mcp setup
For Cursor, VS Code or Claude Desktop, click the button for your app (Claude Desktop's downloads homeshed-mcp.mcpb:
double-click that file). Or add it to Claude Code yourself:
claude mcp add -s user homeshed-mcp -- uvx homeshed-mcp
3. Quit your app fully, open it again, and try it in its chat (Windows: right-click its icon by the clock and
choose Quit; macOS: Cmd+Q; Cursor and VS Code: use agent mode). These work straight away, with nothing else set up:
"What tools do you have from homeshed-mcp?"
"What are github.com's IP addresses?"
"Is port 443 open on example.com?"
"Use the logic solver: which whole numbers x and y give x + y = 10 and x − y = 4?"
"What operating system and CPU is this machine running?"
Stuck? If the terminal says uvx isn't recognised or not found, open a new terminal and try again. Then run
uvx homeshed-mcp doctor: it checks everything and gives you the exact command to fix anything that's missing. If your app
can't start uvx (common for apps opened from the macOS Dock), put the full path that which uvx prints into its MCP
settings in place of uvx.
uvx homeshed-mcp · pipx run homeshed-mcp · pip install homeshed-mcp && homeshed-mcp (in a virtual environment)
Claude Desktop
Easiest: download homeshed-mcp.mcpb from the latest release and
double-click it. Or add this to claude_desktop_config.json (Settings → Developer → Edit Config):
Cloud providers you choose to use, with your own keys (all settings)
ENABLE_TOOLS
Switch on write tools, e.g. git.commit,git.push or a whole group, git.* (dev.* runs code: opt in only if you mean it)
DATA_DIR, MEMORY_DB_PATH
Where it keeps its data and memory
Keep keys out of config files. A key passed with -e is saved in plain text in that client's config. Where
your client supports it, point at an environment variable instead, and never commit a config that holds a key.
New to terminals? Follow the step-by-step guide: every step explained, with what you
should see after each one.
Run it as a server for all your apps (Docker)
Run it once and connect every assistant, agent and machine to it, each with its own key, grants and limits.
On the server (it needs Docker, and uv from step 1 above):
git clone https://github.com/keefng8/homeshed-mcp.git && cd homeshed-mcp
uvx homeshed-mcp init # writes .env here (token, vault key, allowed hosts) and prints your owner token once
docker compose up -d # listens on 127.0.0.1:8765
Then, on the machine where your AI app runs (the same machine here):
Put the token init printed in an environment variable named HOMESHED_TOKEN:
claude mcp add -s user --transport http homeshed-mcp 'http://127.0.0.1:8765/mcp' --header 'Authorization: Bearer ${HOMESHED_TOKEN}'
Keep the single quotes: Claude Code then saves only the variable's name and reads the token when it connects, so the
token never goes into its settings file. The server keeps its copy in .env (git ignores it; back it up, since
init shows the token only once). To share the setup with a team, commit a .mcp.json that names the variable
("Authorization": "Bearer ${HOMESHED_TOKEN}"), never the token itself. Better still, give each app its own key:
Connect Claude Code to your server. To connect from other machines, see
configuration.
Add the Control Panel (optional)
A web page for your install, on your own machine: see at a glance what's running and what it has saved you, switch any
tool off, give each app its own key, and keep your keys encrypted in one place. HomeShed never needs it. Add it now,
later, or not at all, and remove it without touching HomeShed.
Page
What you get
Overview
Is everything working? What your AI just did, who's connected, and what your setup has saved
Models and Reasoning
Which AI answers first and why; try the logic solver and the other reasoning tools by hand
Tools
Every tool, how often it's used, and an on/off switch for each
API access
A key for each app or agent, with only the tools you grant, a rate limit and an expiry
Keys and passwords
Stored encrypted by HomeShed; your AI uses them without ever seeing them
Containers, Uptime, Savings
Your Docker containers, your Uptime Kuma checks, and the tokens kept out of your AI's context, once you use them
With Docker, in the HomeShed folder:
docker compose --profile panel up -d
docker compose logs panel # the first-run password, printed once
Without Docker: make a folder for it, open a terminal there and run uvx homeshed-mcp init once (skip this if you
already did). Then, in that folder:
uvx homeshed-mcp serve --http # HomeShed as a server; leave it running
uvx --from "homeshed-mcp[panel]" homeshed-mcp panel # in a second terminal
Then open http://127.0.0.1:9090 and sign in. The panel answers on this machine only and always asks for a password.
Every page says Not set up yet, and what it needs, for anything you haven't added. More:
the panel's README and its page-by-page guide.
Connect a chat app with sign-in (OAuth)
Chat apps can connect by signing in, so nobody copies a token. HomeShed uses the standard MCP sign-in (OAuth 2.1
with PKCE, dynamic client registration and client metadata documents), so any MCP app that supports sign-in can
connect; it's tested with Claude's custom connectors. You need
the server running (Docker, above), the Control Panel (to approve each sign-in), and an https address the chat app can
reach it at: a service that gives your server a public web address, such as Cloudflare Tunnel, Tailscale Funnel or
Caddy.
In .env, set MCP_PUBLIC_URL to that address and add its name to MCP_ALLOWED_HOSTS, for example:
Then run docker compose up -d again (a plain restart doesn't read .env changes). With MCP_PUBLIC_URL
unset, sign-in is off.
In the chat app, add a custom connector with https://mcp.example.com/mcp and choose sign-in (in Claude: "Sign in
now", "Use Claude's published identity" or "Register automatically").
A page opens with a 6-digit code. On the Control Panel, press Waiting for you at the top of the page. Check the
Sign-in waiting card shows the same code, give the app a name, choose Read-only (recommended), and press
Approve.
To skip step 3 next time, tick Trust this app on the browser that asked before you approve. The same app,
signing in again from that browser to the same return address, is then approved without waiting, for 90 days (up
to 50 trusted browsers; not while the app is suspended). The API page lists them, each with Remove. Trust
belongs to that one browser, never to the app's name, because anyone can start a sign-in as a public app.
Each sign-in is then an app on the API page: its grants, tool view, limits, suspend and delete work as for any app, and
deleting it (or rotating its key) ends its sign-in. Access tokens last an hour and refresh for 60 days; only their
SHA-256 hashes are stored. A chat app left unused for 60 days signs in again. A sign-in waits 10 minutes for you, then
expires. Approve only a sign-in you just started yourself, with the same code on both screens: anyone who can
reach the address can start one and call themselves "Claude".
What your AI can do
flowchart LR
C["Claude Code · Claude Desktop<br/>Cursor · VS Code · any MCP client"] -- "one endpoint" --> R["HomeShed<br/>keys · grants · limits · audit"]
R --> T["Built-in tools<br/>memory · git · files · network · logic solver · workflows"]
R -. "if you run one" .-> L["Your model<br/>Ollama · llama.cpp · LM Studio"]
R -. "your keys" .-> K["Cloud models<br/>any OpenAI-compatible provider"]
R -. "optional" .-> O["Docker · Uptime Kuma · ntfy<br/>memory-core · code graph"]
Area
Works out of the box
Connects to what you already run
Reasoning
Logic and constraint solving (Z3), task routing, complexity scoring
Break down, delegate and run tasks on your model
AI
Ask your model, or cloud models with keys you bring; text to speech with Google's Chirp 3 HD voices
Memory
Facts by category, relevance-ranked recall, a memory per project
A self-hosted memory-core instead of the built-in store
Code & git
Status, diff; commit, push, pull, clone, branch (off until you enable them); find dead Python files; catch webhooks that lose retries; six silent Strapi bugs
Build, lint and test runners (off, opt-in)
Machines
System info and health, DNS lookup, port checks, file listings
Docker containers, Uptime Kuma, ntfy notifications; check your own public sites for exposed admin pages, /.env and /.git
Knowledge
A known-bugs list: "has this error been seen before?"; find API keys left in your Claude Code history, and where to rotate them
Code-graph questions (graphify)
Publishing
Is a repo ready for GitHub (with a fix per gap); do the docs match the code; private details and secrets before you publish; release progress an agent reports
Glue
Chain tools into one workflow; find the right tool from plain English
Tools
173 tools in 43 groups. write tools change something; 🔒 = off until you enable it (see Security).
Tool
What it does
Risk
Needs
agents.inbox
Your own messages from other agents, newest first (unread by default; reading marks them read). The owner may inspect one agent's mailbox, read-only.
write
nothing
agents.list
The other AI apps connected to this tool server that you can message (and the owner): id, label, last seen, and your unread messages from each.
read
nothing
agents.roster
Who's who among the agents: each one's name, role and how to reach it (SendMessage, cloud or mailbox), owner-confirmed rows first.
read
nothing
agents.roster_set
Add yourself or another agent (a cloud session, a mailbox-only app) to the roster with its role; the owner confirms it in the Control Panel.
write
nothing
agents.send
Leave another connected AI app a short message (1-2000 characters) it reads with agents.inbox; to="owner" goes to the owner's inbox instead.
write
nothing
Tool
What it does
Risk
Needs
apis.find
Find APIs in the shared catalog by need, e.g. 'text to speech' or 'free web search'.
read
nothing
apis.list
List APIs in the shared catalog (what APIs exist, cost, local vs cloud, status, how to use), filtered by category/cost/local/status. Never contains secrets.
read
nothing
Tool
What it does
Risk
Needs
approvals.status
What happened to one request that waited for the owner (a shared-memory write, a Proxmox change, a shop request or a message to the owner): waiting, approved, declined, expired, withdrawn or parked, and who decided. An app sees only its own.
read
nothing
Tool
What it does
Risk
Needs
backup.export
Save HomeShed's settings and state (schedules, watches, app access, to-do list, approvals, observations) to one zip; vault key values never included, only their names. Owner only.
write
nothing
backup.restore
Put a backup's state back: a dry run lists what changes and gives a confirm code; the restore makes a safety backup first. Owner only.
write
nothing
Tool
What it does
Risk
Needs
bugs.export
Export the public known bugs as a shareable feed, cleaned of secrets, private addresses and user folders.
read
nothing
bugs.find
Has this error been seen before? Paste it and get the known cause and fix.
read
nothing
bugs.list
List known bugs, newest first, by status or component.
read
nothing
bugs.report
Record a known bug (or a new occurrence of one) with its cause and fix, so nobody hits it twice.
write
nothing
bugs.seen
A tool call failed: count it, and suggest it as a bug for the owner once it comes back in another session. Sent by the failure hook.
write
nothing
bugs.sync
Fetch the HomeShed Pro known-bugs feed with this install's Pro key and merge it in, so bugs.find knows every fix Pro members get.
write
a Pro key (Settings > Pro membership)
Tool
What it does
Risk
Needs
code.dead_scan
Walk a Python project's import graph from its real entry points: files nothing reaches, and init.py re-exports nothing uses (delete-with-care).
read
nothing
code.webhook_retry_check
Find webhook handlers whose catch block swallows the error and answers 200, so the sender (PayPal, Stripe) never retries.
read
nothing
Tool
What it does
Risk
Needs
commerce.requests.approve_housekeeping
A bot the owner named (Settings > Shops and social > "Bots that may approve listing housekeeping") approves one waiting Etsy details card that only changes delivery profile, shop section, production partners, materials, category, attributes or photo alt text. Prices, words, photo adds, removals or moves, publishing and Pinterest still wait for the owner. Logged as the bot's.
write
nothing
commerce.requests.list
An app's own shop requests (Printify publishes, live-product updates, Etsy listing edits): what still waits for the owner, and the owner's decisions of the last 7 days by default, up to 30 (approved, declined, expired), with notes. Check this instead of assuming something still waits.
read
nothing
Tool
What it does
Risk
Needs
dev.build
Run a build command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step. The toolchain must be installed there.
write 🔒
nothing
dev.lint
Run a lint or code-quality command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step. The linter must be installed there.
write 🔒
nothing
dev.node
Run a Node.js command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step. Node must be installed there; the Docker image doesn't include it.
write 🔒
node on PATH
dev.python
Run a Python command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step.
write 🔒
nothing
dev.test
Run a test-suite command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step. The test runner must be installed there.
write 🔒
nothing
Tool
What it does
Risk
Needs
docker.container.inspect
Inspect a container's config, networking and mounts. Env values withheld by default.
read
Docker socket
docker.container.list
List containers on the target Docker host, running or all.
read
Docker socket
docker.container.logs
Fetch recent log lines from a container.
read
Docker socket
docker.container.restart
Restart a container. dry_run defaults true and IS the confirmation step.
write 🔒
Docker socket
docker.container.start
Start a stopped container. dry_run defaults true and IS the confirmation step.
write 🔒
Docker socket
docker.container.stop
Stop a container. dry_run defaults true and IS the confirmation step.
write 🔒
Docker socket
docker.network.list
List Docker networks on this host, including which containers are attached to each.
read
Docker socket
docker.volume.list
List Docker volumes on this host: name, driver, mountpoint, creation time.
read
Docker socket
Tool
What it does
Risk
Needs
docs.read
The text of a PDF, Word (.docx), Excel (.xlsx) or CSV file on this server, locally and free; long documents read on with offset; scanned PDFs say they have no text layer.
read
pypdf, openpyxl, defusedxml
Tool
What it does
Risk
Needs
email.send
Send an email from the owner's own address (SMTP) after he approves it in the Control Panel's Messages; nothing goes out without him. Plain text, up to 10 recipients.
write
an SMTP mail account (Settings > Email, SMTP_PASSWORD)
email.status
Your emails and where each is: waiting for the owner, sent, cancelled, expired or failed.
read
an SMTP mail account (Settings > Email, SMTP_PASSWORD)
Tool
What it does
Risk
Needs
etsy.ledger
What Etsy actually charged and paid the shop (listing, renewal, transaction and processing fees, sales, deposits), in pounds, paged, with a per-type sum. Read-only.
read
the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.listing.deactivate
Take one of the shop's active Etsy listings off sale at once (a brake for a listing that fails a check). No approval step: its own switch, a daily cap, audited, and the owner gets a push with the reason. Etsy's Shop Manager re-activates it.
write
the owner's commerce_etsy_enabled and commerce_etsy_deactivate_enabled switches, an Etsy connection made with listing edits (listings_w)
etsy.listing.get
One Etsy listing in detail: title, description, price, tags, materials, views, favourites. Read-only.
read
the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.listing.update
Ask to set an Etsy listing's category, materials, production partners, delivery profile, attributes (colour, occasion, recipient, holiday), extra photos (up to 5 at a time, shown to the owner as thumbnails) and the order of its photos. Nothing changes until the owner approves it; only what differs is sent; details (not photos) are re-queued after a Printify re-publish.
write
the owner's commerce_etsy_enabled and commerce_etsy_write_enabled switches, an Etsy connection made with listing edits (listings_w), the owner's approval of each change
etsy.listings.list
The Etsy shop's listings, compact and paged: id, title, state, price, quantity. Read-only.
read
the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.order.get
One Etsy order: status, money, items and shipments; no buyer personal details. Read-only.
read
the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.orders.list
The Etsy shop's orders (receipts), compact and paged; no buyer names, emails or addresses. Read-only.
read
the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.shipping_destinations
Where one of the shop's delivery profiles delivers: countries or regions, prices, delivery days, and whether any is in the EU.
read
the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.shop.get
The configured Etsy shop: name, currency, listing and sales counts, reviews, vacation mode. Read-only, proxied (the app never holds the key).
read
the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.shop.update
Ask to set the Etsy shop's title, announcement, messages to buyers after a purchase and additional policies, and to add shop sections. Nothing changes until the owner reads the full new texts and approves; only what differs is sent. Etsy's API has no About section.
write
the owner's commerce_etsy_enabled and commerce_etsy_shop_write_enabled switches, an Etsy connection made with shop edits (shops_w), the owner's approval of each change
Tool
What it does
Risk
Needs
files.list
List a directory's entries, ls -F style by default ("docs/", "notes.txt (1.2 KB)"); detail=full gives type, size, modified time and permissions. At most 100 unless limit says otherwise, with total and more telling what was left out. Metadata only, never file content.
read
nothing
Tool
What it does
Risk
Needs
git.branch
Create and/or switch to a git branch. Fully autonomous, no confirmation step.
write 🔒
nothing
git.clone
Clone a git repository. Fully autonomous, no confirmation step.
write 🔒
nothing
git.commit
Stage and create a git commit. Fully autonomous, no confirmation step.
write 🔒
nothing
git.diff
Unified diff for working-tree or staged changes in a git repository.
read
nothing
git.pull
Pull changes into the current branch. Fully autonomous, no confirmation step.
write 🔒
nothing
git.push
Push the current branch to a remote. Fully autonomous, no confirmation step.
write 🔒
nothing
git.status
Branch, ahead/behind tracking, and staged/unstaged/untracked files for a git repository.
read
nothing
Tool
What it does
Risk
Needs
graphify.query
Ask an already-generated graphify code graph a question via BFS/DFS traversal. Locator, not an answerer — returns src= paths to read, not final answers.
read
graphify, and a graph built for the project
Tool
What it does
Risk
Needs
image.cancel
Stop one of your image jobs: a waiting one leaves the line, a running local one is stopped. An app can cancel only jobs it started; the owner any. A paid provider's job can't be stopped once sent.
write
the local image service
image.carousel
Designs as 1080x1350 (4:5) or 1080x1920 (9:16) social slides, or a 2000x2000 (1:1) Etsy listing photo, on their own background, saved in the images promo folder for threads.publish.
write
the local image service
image.compare
Is a scene's print exactly the reference's (the mockup it was made from, or the print file), and does the tee stand out from the background? Finds the print, scores structure and colour, looks for added text, and flags a tee that blends into its background. Free, local CPU.
read
the local image service
image.delete
Delete one image the tool server keeps (an image.store upload or a paid provider's image) straight away. An app deletes only its own; the owner token may delete any.
write
nothing
image.describe
Short, plainly visible details of a design's artwork (e.g. "long gold ears"), never a breed, name, fact or guess: for writing posts and listings about a design without seeing it. Claude Haiku through the llm relay.
read
llm relay: anthropic switched on (CLAUDE_WORKSPACE_API)
image.embed
An image's SigLIP 2 embedding (768 numbers, L2-normalised; google/siglip2-base-patch16-224, Apache-2.0), for a classifier trained on the owner's ratings. Free, local CPU only, never the GPU.
read
the local image service
image.fetch
Download a finished image job's full-size original (byte for byte, the provider's own format) by job_id, not the 1024 px preview image.status gives.
read
GPU image service (IMAGE_BASE_URL) for local jobs
image.generate
Start an image generation job; returns a job_id immediately. Default: free local GPU (stable-diffusion.cpp), whose default model FLUX.1-schnell is commercial-safe (Qwen-Image-2.1, only when named, is NON-COMMERCIAL). Opt-in PAID providers (openai, stability, replicate, fal, together, xai) via provider=..., IMAGE_DEFAULT_PROVIDER, or require_commercial=true, which refuses models whose outputs can't be sold.
write
GPU image service (IMAGE_BASE_URL) for local-sdcpp, a provider API key in the vault for a paid provider
image.history
Recent generated images with the prompt each was made with, the model, seed and size, newest first: local and paid-provider images together. Read-only, no image data.
read
GPU image service (IMAGE_BASE_URL) for local images
image.ip_check
Vision check before listing: a brand, a known character, a real person or unsafe content in an image; for a lifestyle hero photo, a visible child (blurred background included) or something covering the print (pass image.compare's print box). Claude Haiku via the llm relay, about $0.0005 a call. Fail closed: ok false means NOT clear.
write
the owner's llm_provider_anthropic_enabled switch and an llm_daily_cap_anthropic above 0, CLAUDE_WORKSPACE_API in the vault
image.preview
A print file on a plain flat tee (sand, white, navy, black or any #rrggbb), front or back, at its true size: a 1024 px JPEG so the owner rates exactly what will be printed. Free, local CPU, no person or model.
write
the local image service
image.print_file
Turn a design on a plain background into transparent print files at a print area's exact size (300 DPI, full colour or flat colours), light-tee and dark-tee (keyline) versions.
write
GPU image service (IMAGE_BASE_URL) for local jobs
image.promo_card
A branded 1080x1920 (9:16) or 1080x1350 (4:5) promo card around a real product mockup: logo, headline, benefit, real GBP price, Shop now button and link, in a bold 'drop' or premium 'editorial' template, optionally on a brand frame. Saved in the images promo folder for threads.publish.
write
the local image service, a brand kit on the image service
image.prompts
List, add, edit or remove the owner's saved image prompts (shared with the Control Panel).
write
GPU image service (IMAGE_BASE_URL) for local jobs
image.providers.list
Which image providers and models exist, whether each is switched on (owner-only switches; read-only here), configured (key stored: yes/no only), usable now (daily cap), its licence, whether outputs may be sold (commercial_use true/false/check), and cost (free local vs paid per image).
read
nothing
image.queue
The local image service's line: busy or not, the image being made and the ones waiting.
read
GPU image service (IMAGE_BASE_URL) for local jobs
image.status
Check an image generation job (local or paid provider): running/done/failed, progress, elapsed time, licence; optionally the image.
read
GPU image service (IMAGE_BASE_URL) for local jobs
image.store
Keep an image you already have (PNG, JPEG or WebP, base64, up to 10 MB and 4096 px a side) for 7 days and get back a name the other image tools take, such as image.generate's input_images. Re-encoded on the way in: EXIF/GPS metadata removed.
write
nothing
image.text_check
Does a design image carry text: words, pseudo-text or a signature-like mark? Free and local (RapidOCR on the image service, ~1-2 s). Returns ok/text_found and every candidate region with its corner and score.
read
the local image service
Tool
What it does
Risk
Needs
inbox.amend
Correct your own open message to the owner (text, command or need); shown as edited.
write
nothing
inbox.replies
Your messages to the owner and his replies, newest first.
read
nothing
inbox.send
Leave the owner a message on the Control Panel (and his phone): a note, a command for him to run, or a decision he needs to make.
write
nothing
inbox.withdraw
Take back your own message to the owner; it leaves his list at once.
write
nothing
Tool
What it does
Risk
Needs
instagram.publish
Post one image, a carousel (2-10 images) or a video as a Reel, with a caption, to the owner's connected Instagram professional account. Public; off until the owner switches it on.
write
Instagram connected in Settings > Shops and social, the owner's switch: Let apps post to Instagram
instagram.status
Whether Instagram is connected and posting is on, the account, and posts in the last 24 hours.
read
nothing
Tool
What it does
Risk
Needs
llm.chat
One chat turn with a PAID language model (xAI Grok, Anthropic Claude, OpenAI or Google Gemini; xai by default), relayed so the caller never holds the key: the key stays in the owner's vault. Off until the owner switches the provider on and sets a daily cap (Settings > Language models); refused with the reason when off, keyless or capped. max_tokens up to 16,000; continue_if_cut asks once more when an answer stops at max_tokens and joins the two. effort (anthropic only: low, medium, high, xhigh, max) sets how hard Claude thinks, so thinking can't eat the whole max_tokens. Returns text (up to 64,000 characters), model, usage (tokens, cost) and a truncated flag.
write
the owner's llm_provider_enabled switch and an llm_daily_cap above 0, for the provider used, that provider's key in the vault: XAI_API_KEY, CLAUDE_WORKSPACE_API, OPENAI_API_KEY or GEMINI_API_KEY
llm.providers.list
Which paid language-model providers llm.chat relays to and whether each is usable now: the owner's switch (read-only here), key stored (yes/no only), why not, today's request and token caps and use, today's cost (all apps and per client), and model prices.
read
nothing
Tool
What it does
Risk
Needs
local_ai.ask
Ask your own model (LOCAL_AI_MODEL) a question, or a cloud model you've added a key for. Cheap local-first answers before escalating to a bigger model.
read
model server (LOCAL_AI_BASE_URL) or a cloud key
local_ai.classify_complexity
Score a request's complexity 0-100 with a fast, deterministic, offline regex heuristic. Advisory only -- never routes or executes anything.
read
nothing
Tool
What it does
Risk
Needs
mcp.install_links
One-click install buttons, one-line commands and per-app configs for any MCP server, from a package name or URL.
read
nothing
Tool
What it does
Risk
Needs
memory.capture
Write a fact/decision/preference into persistent memory (the built-in store, or a self-hosted TDAI memory-core), recallable in future sessions via memory.recall.
write
nothing
memory.recall
Read back raw conversation history previously written with memory.capture for a given session_id, from the built-in store or a self-hosted TDAI memory-core.
read
nothing
memory.recall_facts
Read back one category of the project's durable facts tier — scoped, fast, no unneeded text from other categories.
read
nothing
memory.recall_relevant
Recall messages from a session ranked by relevance to a query, not just chronological order.
read
nothing
memory.remember_fact
Write a durable, high-value fact into the dedicated facts tier of persistent memory — outranks topic-scoped memory.capture entries on recall.
write
nothing
memory.stats
How much memory has been read and written: an app's own totals by category, or every app's share for the owner.
read
nothing
Tool
What it does
Risk
Needs
network.dns.lookup
Resolve a hostname to its IP addresses (A/AAAA only).
read
nothing
network.exposure_check
What your own public sites answer on the paths attackers try first: admin panels, /.env, /.git, status pages. Read-only; public hosts only.
read
internet access
network.port_check
Test TCP connectivity to a host:port -- a real connection attempt, not a guess.
read
nothing
Tool
What it does
Risk
Needs
notify.send
Send a push notification via this deployment's self-hosted ntfy instance.
write
ntfy (NTFY_BASE_URL, NTFY_AUTH_TOKEN)
Tool
What it does
Risk
Needs
observe.list
List observations from the persistent observation log, filtered by status and rule.
read
nothing
observe.log
Record a rule violation, user correction, or improvement gap in the persistent observation log; flags repeat violations of the same rule for escalation to a mechanical guard.
write
nothing
observe.update
Change an observation's status (actioned, declined, superseded, parked, open) and append a dated resolution note.
write
nothing
Tool
What it does
Risk
Needs
pinterest.board.create
Ask to make a Pinterest board. Nothing is made until the owner approves it in the approvals bar.
write
the owner's social_pinterest_enabled switch, Pinterest connected, the owner's approval of each board
pinterest.boards.list
The connected Pinterest account's boards: id, name, privacy, pin count.
read
the owner's social_pinterest_enabled switch, Pinterest connected
pinterest.pin.create
Ask to make one Pinterest pin: image, title, description (with "AI-assisted design." and Pinterest's AI disclosure when AI helped), alt text and a link to one of the shop's own active Etsy listings. Nothing is pinned until the owner approves THIS pin in the approvals bar; no app or AUTO mode can approve one (Pinterest's rule).
write
the owner's social_pinterest_enabled switch, Pinterest connected, the owner's approval of each pin
pinterest.status
Whether Pinterest is connected and pinning is on, Trial (sandbox, only the owner sees pins) or Standard access, the account, and pins in the last 24 hours.
read
nothing
Tool
What it does
Risk
Needs
printify.blueprint.get
One Printify blueprint (blank product): title, brand, model and its description as plain text, with the fabric, fibre and weight lines a listing's material bullet needs. Read-only.
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN)
printify.blueprints.list
Printify's catalogue of blank products, searchable and paged. Read-only.
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.mockup.fetch
Copy one of a product's Printify mockups into the image store and return its image name, for image.carousel (watermarked slides) and threads.publish.
write
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN)
printify.order.get
One Printify order: status, totals, items, shipments; no delivery address. Read-only.
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.orders.list
The configured Printify shop's orders, compact and paged; no delivery addresses. Read-only.
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.print_provider.get
One Printify print provider (maker): city, region and country (to confirm a UK maker; print_providers.list has no location, KB-0067) and the blueprints it makes. Read-only.
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN)
printify.print_providers.list
The print providers that make one Printify blueprint: id, title, country. Read-only.
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.product.create
Upload a print file and make an UNPUBLISHED product in the owner's Printify shop (for Printify's mockups). Off until the owner switches it on; daily cap.
write
PRINTIFY_API_TOKEN with uploads.write and products.write, PRINTIFY_SHOP_ID, the owner's switches: Printify read + create
printify.product.delete_draft
A bot the owner named (Settings > Shops and social > "Bots that may delete Printify drafts") deletes one UNPUBLISHED Printify draft, such as a test or a duplicate. Published products, ones mid-publish, waiting for publish approval or published today are refused. The draft is saved first and each delete audited with its reason.
write
nothing
printify.product.get
One Printify product in detail: its enabled variants with price and cost (paged, or filtered to chosen variant ids), tags, blueprint, provider and where it's published.
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.product.publish
Ask to publish a Printify draft to the owner's connected Etsy shop. It waits for the owner's approval in the Control Panel; only then does it go live.
write
the owner's commerce_printify_enabled and commerce_printify_publish_enabled switches, a Printify shop connected to Etsy
printify.product.update
Edit an unpublished Printify draft's title, description, tags, variant prices and SKUs, or replace its print areas (e.g. a back print plus a left-chest front print). Drafts only (never published, mid-publish or awaiting publish approval), never under the margin floor (20%, hoodies 15%) after Etsy's fees, audited with the old values kept.
write
the owner's commerce_printify_enabled and commerce_printify_write_enabled switches
printify.product.update_live
Ask to change a published Printify product's title, description, tags or prices on the owner's Etsy shop. Nothing changes until the owner approves it in the Control Panel; then Printify edits it and re-publishes only the changed parts. SKUs never change on a live product; never under the margin floor (20%, hoodies 15%); capped and audited.
write
the owner's commerce_printify_enabled and commerce_printify_live_update_enabled switches, the owner's approval of each update
printify.products.list
The configured Printify shop's products, compact and paged. Read-only.
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.shipping
Delivery prices for one blueprint from one print provider: handling time, and per group of variants and countries the first and each additional item's price, in Printify's currency (never converted).
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN)
printify.shops.list
The Printify shops the token can see: id, title, sales channel. Read-only, proxied.
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.variants.list
One blueprint's variants from one print provider: id, colour, size and print-area sizes in pixels (cost appears only on a created draft).
read
the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
Tool
What it does
Risk
Needs
proxmox.health
The whole Proxmox cluster at a glance: quorum, each node's CPU, RAM and system disk, storage pools, VMs and containers running, and the alarms active now (as on the Control Panel's Proxmox tab). Read-only.
read
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.nodes.list
List every node in the Proxmox cluster (one token covers the cluster): online or not, CPU and memory use, uptime, plus the cluster's name and quorum. Read-only.
read
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.storage.list
Storage pools on Proxmox and how full they are, on every node or one. Read-only.
read
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.tasks.list
Recent Proxmox tasks on a node (starts, stops, snapshots, backups) and how they ended; follow up an approved change here. Read-only.
read
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.vm.create
Create a new VM (qemu) or container (lxc) with Proxmox's own create options. dry_run defaults true; dry_run=false only queues it for the owner's approval. Never replaces a guest; no secrets in options.
write
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.vm.power
Start, stop, shut down or reboot a VM or container. dry_run defaults true; dry_run=false only queues it for the owner's approval (POST /proxmox/pending//approve).
write
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.vm.snapshot
Take a snapshot of a VM or container. dry_run defaults true; dry_run=false only queues it for the owner's approval. Never deletes or rolls back.
write
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.vm.status
One VM's or container's live status, found cluster-wide by vmid (node optional): running or not, lock, CPU, memory, disk, network. Read-only.
read
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.vms.list
List VMs (qemu) and containers (lxc) across the whole Proxmox cluster, with status, CPU, memory and uptime; optional node filter. Read-only.
read
Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
Tool
What it does
Risk
Needs
publisher.sign
Ask for a read-only library script's current version to be signed with HomeShed's publisher key; the owner reads the code and says Yes in the Control Panel.
write
nothing
Tool
What it does
Risk
Needs
reasoning.decompose_task
Break a task description into an ordered list of subtasks via the local model.
read
model server (LOCAL_AI_BASE_URL) or a cloud key
reasoning.delegate
Route a task and, if the local model is recommended, actually ask it. Claude path never fakes an answer.
read
model server (LOCAL_AI_BASE_URL) or a cloud key
reasoning.pipeline
Route, delegate, and persist a task's outcome to shared memory -- the full diagram in one call.
write
model server (LOCAL_AI_BASE_URL) or a cloud key
reasoning.route
Recommend whether a task should go to the local model or Claude, advisory only.
read
nothing
reasoning.solve
Solve a constraint-satisfaction/logic problem via Z3, expressed in standard SMT-LIB2 text.
read
nothing
Tool
What it does
Risk
Needs
registry.find
Find which capability best matches a natural-language request. Exact ID, then alias/keyword, then local-AI fallback. Never executes anything.
read
nothing
registry.version
A package's latest released version and when it went up, from PyPI, npm or GitHub releases, in a few hundred characters. Read-only, no keys.
read
nothing
Tool
What it does
Risk
Needs
repo.docs_check
Check a project's README and docs/ against its code: link anchors that point at real headings, documented settings the code actually reads, and documented CLI commands and options that exist.
read
nothing
repo.leak_scan
Find private details (your names, domains, private addresses, folder paths) and secrets (API keys, tokens, private keys, passwords in settings) in a folder about to go public: file, line and pattern name, never the matched text.
read
nothing
repo.progress
How far each project's release has got, as its agent last reported: percent of gates done, measured numbers such as readiness, what waits on the owner and since when, and the last 20 updates.
read
nothing
repo.progress_update
An agent preparing a project for release reports how far it has got (pass/fail gates with evidence, measured numbers, what waits on the owner), so the owner sees a percentage on a dashboard.
write
nothing
repo.readiness
How ready a project folder is to publish on GitHub: the files a pro-level repository has (README, licence, security policy, CI, templates...), with a concrete fix for each gap, plus checks inside a Dockerfile and compose file.
read
nothing
repo.stats
How a public GitHub repository is doing: stars, forks, watchers, open issues, release downloads, PyPI downloads, and views, clones and referrers when a GitHub token can read its traffic. Daily traffic is kept past GitHub's 14 days.
read
nothing
Tool
What it does
Risk
Needs
schedule.add
Run a read-only tool on a timetable (daily, weekly, every N hours or cron), as its maker, with a phone alert on change, always, on error or never. Write tools are refused.
write
apscheduler
schedule.list
Your schedules with next run, last run, whether it worked and the last 5 run summaries.
read
apscheduler
schedule.pause
Pause a schedule or resume it (also clears a pause after repeated failures).
write
apscheduler
schedule.remove
Delete one of your schedules; it stops at once.
write
apscheduler
Tool
What it does
Risk
Needs
secrets.transcript_scan
Find API keys, tokens and passwords saved in Claude Code's own transcripts, and say where to rotate each. Never returns a secret: kind, length and a fingerprint only.
read
nothing
Tool
What it does
Risk
Needs
spend.cap_set
Owner sessions only: set the daily dollar cap (0-5) of an app the owner opened to it, such as a coordinating app setting caps for the apps it runs. Other apps keep the owner-set cap.
write
nothing
spend.today
What each app (API client) has spent today on paid images and language-model calls, in dollars, against the daily cap the owner set for it. An app at its cap gets SPEND_CAP_REACHED on its paid calls; free and local tools keep working.
read
nothing
Tool
What it does
Risk
Needs
strapi.check
Lint a Strapi v5 project for six known silent bugs (missing pagination, v4 .attributes, bad filter paths, NODE_ENV, /api/api routes) and optionally probe its live /admin.
read
nothing
Tool
What it does
Risk
Needs
system.health
Check whether the configured dependencies (memory-core, the first local model, the app store backend, the Docker daemon) are reachable right now. Ones that aren't configured are skipped.
read
nothing
system.info
Hardware and OS information for the machine HomeShed runs on (your computer, or its container).
read
nothing
system.savings
Tokens saved today and per day for the last week, with what they'd have cost at a model's API price.
read
nothing
Tool
What it does
Risk
Needs
threads.insights
Views, likes, replies, reposts, quotes and shares for one of the owner's Threads posts, or the account's follower count with no post id.
read
Threads connected with the insights permission
threads.publish
Post text, one image, a carousel (2-10 images) or a video to the owner's connected Threads account. Public; off until the owner switches it on.
write
Threads connected in Settings > Shops and social, the owner's switch: Let apps post to Threads
threads.replies
The replies to one of the owner's Threads posts (read-only), for answering and for design ideas.
read
Threads connected with the read-replies permission
threads.status
Whether Threads is connected and posting is on, the account, and posts in the last 24 hours.
read
nothing
Tool
What it does
Risk
Needs
tools.call
Run any tool by name with the same checks as a direct call (access, approvals, spend limits). Optional fields keep only the parts of the reply you need; to_file keeps a big reply on the server to read with tools.result.
read
nothing
tools.describe
One tool in full: what it does and its inputs, exactly as the full tool list shows it. Use before tools.call.
read
nothing
tools.find
Find the tools for a job, best first, among the ones this app may use: each with one line on what it does and whether it reads or changes things. Start here, then tools.describe one and tools.call it.
read
nothing
tools.groups
What's here by group (shops, images, memory...), with counts, or the tools in one group with one line each. Only tools this app may use.
read
nothing
tools.result
Read back a reply tools.call kept with to_file, a page at a time, filtered by text or trimmed to fields. Kept 24 hours, only for the app that made it.
read
nothing
Tool
What it does
Risk
Needs
tts.fetch
An MP3 that tts.synthesize made, byte for byte as base64 (audio_b64), so the caller can save it. An app gets only its own files; files are kept 7 days.
read
nothing
tts.synthesize
Speak up to 5,000 bytes of text as an MP3 with a Google Chirp 3 HD voice, saved on the tool server for tts.fetch. Counted against Google's free 1 million characters a month; a piece that would pass the month's cap is refused with TTS_CAP_REACHED (free only unless the owner allows paid characters). provider="elevenlabs" uses the owner's ElevenLabs plan instead.
write
GOOGLE_TTS_SERVICE_ACCOUNT in the vault (a Google Cloud service account key file), ELEVENLABS_API_KEY in the vault, for provider="elevenlabs"
tts.usage
This month's text-to-speech characters against Google's free 1 million and the owner's paid allowance, characters left, the reset date (Pacific time) and each app's calls. provider="elevenlabs" uses the owner's ElevenLabs plan instead.
read
ELEVENLABS_API_KEY in the vault, for provider="elevenlabs"
tts.voices
Google's Chirp 3 HD voices for tts.synthesize: name, gender and language, optionally for one language. Asked of Google at most once a day per language. provider="elevenlabs" uses the owner's ElevenLabs plan instead.
read
GOOGLE_TTS_SERVICE_ACCOUNT in the vault (a Google Cloud service account key file), ELEVENLABS_API_KEY in the vault, for provider="elevenlabs"
Tool
What it does
Risk
Needs
uptime.status
Real Uptime Kuma monitor status, read directly from its database, read-only.
Fetch a public webpage as Markdown via Jina Reader, zero API key required.
read
internet access; pages are fetched through Jina Reader (r.jina.ai)
web.search
Search the web through a self-hosted SearXNG: titles, links and short snippets; read pages with web.read.
read
a SearXNG search engine (SEARXNG_URL); free and self-hosted, no API key
web.watch
Get a phone alert when a web page changes (a price, back in stock, a new post): a schedule that checks it and alerts only when two checks agree.
write
web.read (Jina Reader), schedule.*
web.watch.check
Read a page and compare it with the last look: alert due only when two checks in a row agree on a big-enough change, or the trigger text appears.
read
web.read (Jina Reader), schedule.*
Tool
What it does
Risk
Needs
workflow.run
Chain existing capabilities into one multi-step task, stopping at the first failure.
write
nothing
Every tool has its own page in capabilities/ with inputs, examples and risks.
Security
HomeShed can act on your machines, so it's built to be dull and safe out of the box:
On your own machine (the one-line install) it talks only to the app that started it, with nothing listening
on the network.
As a Docker server, a token on every request, including from localhost, with Host and Origin checks
against DNS rebinding. The one exception is /healthz, which says only {"status": "ok"} so an uptime
monitor can check it. The server refuses to start without a token and a list of allowed hosts.
Listens on 127.0.0.1 by default. Putting it on the internet is opt-in: behind an access proxy such as
Cloudflare Access, or, for chat apps, with sign-in switched on, where
/mcp still needs a token and a chat app gets one only after you approve it on the Control Panel.
Runs as an ordinary user in Docker, not root, and can't rewrite its own code there.
Tools that act on your machines start off. Docker, git writes and code execution each need switching on.
Tools that only keep notes for your AI (memory, observations, known bugs) are on.
Per-app grants: each client gets its own token, tool list, rate limit and expiry, and only sees the tools
it's granted; creating, rotating or suspending one is written to an audit log.
SSRF guard: web.read and the network tools refuse private and metadata addresses.
No telemetry, and requests aren't logged. Each call is recorded as tool name, time, duration and which app,
never its arguments or result; usage counters keep sizes only. Memory, observations and the known-bugs list
store only what your AI saves on purpose, on your machine.
Mounting the Docker socket gives root on that machine, so the compose file leaves it out until you uncomment its
line (how). To report a vulnerability, see
SECURITY.md.
Get HomeShed only from official sources
Popular open-source tools attract look-alike packages and fake copies that carry malware. HomeShed is published
only here:
claude plugin marketplace add keefng8/homeshed-mcp
Anything else using the name, a similar name or this project's logo isn't us. Every GitHub release has a
SHA256SUMS file, and PyPI packages are published from this repo's release workflow with provenance, so you can
check what you install. To check a file you downloaded from a release, compare its hash with the line for it in
SHA256SUMS:
certutil -hashfile homeshed-mcp.mcpb SHA256 # Windows
shasum -a 256 homeshed-mcp.mcpb # macOS and Linux
If they don't match, don't open the file. We never ask for your tokens, keys or passwords, by email, message or anywhere else; your
keys stay in your own HomeShed. If you find a fake copy, please tell us.
What it's not
Not a model provider. It includes no AI model and needs no GPU. It uses a model you run, or cloud keys you bring.
Not a hosted service. You run it yourself, on your own machine or server.
Not a gateway for other MCP servers. Its tools are built in. To put many existing servers behind one door, run a
gateway alongside it.
Not an autonomous agent. It acts only when your AI app calls a tool, and tools that act on your machines
start switched off.
How it compares
Official reference servers
Gateways (Docker MCP Gateway, MetaMCP)
HomeShed
One endpoint for everything
❌ one server per job
✅
✅
Tools built in
➖ each installed separately
❌ bundles servers you add
✅ 173: 72 ready at once, 13 off until you enable them, 88 connect to what you run
Per-app keys, grants, rate limits and audit
❌
➖ varies
✅
Hands routine work to your own model
❌
❌
✅ if you run one
Write tools off until you enable them
➖
➖
✅
Choose something else if you need one focused job done brilliantly (browser automation:
Playwright MCP; library docs: Context7),
or you already run many MCP servers and just want them behind one door (a gateway). They work alongside HomeShed.
FAQ
No. HomeShed doesn't include a model. Without one, the AI tools say they aren't set up and everything else works.
If you run a model, or bring your own cloud keys, routine work can go there instead of your paid assistant.
Only where you point it: your model server, the cloud providers whose keys you add, and your memory store. Two tools
reach outside services, and only when used: web.read sends the page's address to
Jina Reader, which fetches the page, and bugs.find can search public GitHub issues if
you opt in. If you connect HomeShed Pro, it also talks to the Pro website, using your Pro key: to check
your membership and to fetch the packs and the known-bugs feed. Nothing phones home.
If you turned rule packs on: uvx homeshed-mcp packs off (it takes HomeShed's hook out of Claude Code's settings).
Remove it from your app: claude mcp remove homeshed-mcp -s user for Claude Code, or delete it from the MCP
settings (or extensions, for Claude Desktop) of Cursor, VS Code or Claude Desktop.
Free the downloaded files: uv cache clean homeshed-mcp.
Only if you also want your saved memory, keys and settings gone: delete the data folder
(where it is). For Docker, docker compose down -v deletes its volumes.
Only behind an access proxy (for example Cloudflare Access) as well as the token, or with
sign-in for chat apps, where you approve each sign-in yourself. See
Security.
Yes: one Python file plus a JSON manifest, and every MCP client sees it within its grants. See
CONTRIBUTING.md.
Roadmap
✅ available · 🟡 in progress · ⚪ planned
What
✅
173 tools across reasoning, memory, git, Docker, network and more
✅
The front door: five tools that find and run the rest, with trimmed replies and real images (0.7.0)
✅
Sign-in for MCP apps (tested with Claude.ai connectors), approved by you with a matching code (0.7.0)
✅
Per-app keys, tool grants and rate limits, with an audit log of every change to them
✅
Persistent memory, built in, one per project (or connect memory-core)
✅
Observations: log corrections, flag repeats
✅
setup and doctor commands
✅
An optional Control Panel: a web page for your install, added or removed any time
✅
Safe defaults everywhere: local-only listening, write tools off, keys generated for you
✅
One-line install for every major AI app: uvx, one-click buttons, a Claude Desktop extension
✅
Rule packs: checks before Claude Code runs a command or writes a file (your own, or Pro's curated packs)
Want something else? Suggest it; a 👍 on an existing idea helps
us choose what comes next.
HomeShed Pro
Every curated pack and fix, kept up to date.
HomeShed is free and complete, and it stays that way: every tool and all of its memory. HomeShed Pro is part of
Mavis Pro, the membership from the makers of Mavis, a Windows
voice assistant with 124 one-click apps. One membership covers both. It adds:
Never lose your place. Before Claude Code compacts a long session, HomeShed Pro saves a note of
what you were doing and puts it back straight after, so Claude carries on knowing the task. It comes with the Token
Saver pack, and uvx homeshed-mcp packs compact-at 80 sets when compaction starts. Windows and Linux tested; macOS
should work. The note stays on your own machine (how it works).
Every curated rule pack, done for you. You can write your own packs, so why do Pro's? Because these are the
lessons from real Claude Code sessions, already written, tested and kept up to date, and one command installs each:
Token Saver (cuts wasted tokens and time: bounded searches, no waiting in loops, simple work to your own model), Safe Operator (keeps keys and
passwords out of commands, files and the chat, and stops risky commands with the reason), Team Sessions (several
Claude sessions working together: every message checked, nothing handed over unchecked, nobody left waiting),
Release Ready (keeps .env files out of git, plus Docker lockfile hygiene) and Beginner Mode (plain words,
one step at a time, and a question before anything is installed or deleted).
A curated known-bugs feed: fixes other users already found, straight into bugs.find.
Fair terms: packs you've installed keep working if you stop paying.
Pro tools: the to-do list (todo.*) and trend signals (signal.*). Run uvx homeshed-mcp pro update after
connecting (needs HomeShed 0.3.1 or newer); the package is checked against its signature before it's unpacked.
Still to come: the decision tools, file summaries and knowledge search (with their companion services), and
YouTube publishing.
Connect it. On the Pro website, open your account page, then Access keys, and make a key (it starts with
mav_ and is shown once). In the Control Panel, go to Settings → Account and sharing → Pro membership, choose
Paste a Pro key and paste it. Without the Control Panel, run uvx homeshed-mcp pro connect and paste it there.
HomeShed checks the key with the Pro website, then keeps it in its vault. Then install packs: see
Rule packs.
HomeShed never asks for your Pro password; a copy that does isn't ours. Until you connect, nothing is sent to the Pro
website. To stop, choose Disconnect in the same place, and revoke the key on the Pro website.
Contributing
Issues and pull requests are welcome. Start with CONTRIBUTING.md; taking part means following
the Code of Conduct. If HomeShed saves you time or tokens, a ⭐ helps other people find it.
