What Hexsmith does
Hexsmith helps your AI assistant build and run apps for your business.
You say what you need in plain words. Your AI assistant does the building, and Hexsmith keeps the work organised, checked and safe.
This app is where you see your apps, add features, connect your accounts and keep your keys private.
You can switch between Simple and Dev any time in Settings.
Connect your AI assistant
Hexsmith works through an AI assistant on this computer, such as Claude Code, Codex or Copilot.
- Open Your AI assistant in the menu on the left.
- Press Connect next to your AI assistant.
- Close your AI assistant and open it again, so it sees Hexsmith.
If it says Needs a quick update, press Repair. Hexsmith fixes its own settings and keeps a copy of the old ones.
In the app: Your AI assistant
Start your first app
- Open your AI assistant.
- Ask it to start a new app with Hexsmith, and say what the app is for.
- Answer its few questions here, in My apps. It shows you a short plan.
- Say yes to the plan. Your AI assistant builds the app and tells you when it is ready.
Your apps are listed in My apps. Open one to see what has been done and what is left.
Your AI assistant always asks you before anything that publishes, messages customers, spends money or cannot be undone.
In the app: My apps
Add features
Features are ready-made parts your app can use, like payments, bookings, email or a shop.
- Open Add features.
- Pick what you want to do, or search for it.
- Open a feature to read what it does, then press Add.
My features shows everything you have added. Kits are sets of features for one goal, and you choose which parts to keep.
In the app: Add features
Connect your accounts
Some features need one of your accounts, such as your payment or email service.
- Open Connected services and pick the service.
- Follow the steps. Each one says where to find what it asks for.
- Press Test now to check that it works.
Your keys stay private on this computer, sealed in a vault. If a service stops working, Hexsmith tells you on Home.
In the app: Connected services
Things that run on their own
Your apps can do things by themselves, like reminders, reports and follow-ups.
See them in Automatic tasks, and add ready-made ones from Ready to add.
To hear about problems even when this app is closed, turn on Check while the app is closed in Settings, General.
In the app: Automatic tasks
Keep your keys safe
Privacy & backups shows where your keys are sealed on this computer.
Make a recovery file and keep it somewhere safe, away from this computer. With it, you can open your keys on a new computer, or after a password reset.
When Hexsmith changes your AI assistant's settings, it keeps a copy first. You can put any copy back from the same page.
In the app: Privacy & backups
When something goes wrong
Home lists anything that needs you, each with a button to fix it.
If your AI assistant does not seem to know Hexsmith, open Your AI assistant, press Repair if you see it, then restart your AI assistant.
To ask for help, open Settings, About and press Save a problem report. It saves a file in Downloads that you can send to support. It never holds your passwords or keys.
Getting started
Install, licence, connect an agent, start a project.
Hexsmith is the workbench your coding agent builds on. The agent does the work; Hexsmith gives it structure: a staged plan, a versioned timeline with checkpoints and undo, containment so it only touches what it should, signed armaments (packages) for common jobs, and a sealed vault for the keys those packages use.
This app is the control centre. It shows your projects, what is installed, the services you've connected and the agents on this machine, and fixes most problems in place.
In four steps
- Install Hexsmith: the Windows installer or the macOS .pkg puts both this app and the
hexsmith / hxs command on your machine. - Activate your licence on the Plan page: sign in with Google, or activate a
license.key file (you can drag it onto this window). The Free edition needs no licence. - Connect your coding agent on the Agents page, then restart the agent.
- In the agent, start a project: run
/hexsmith:new in Claude Code, or ask any connected agent to start a new Hexsmith project. The setup opens in this app's Console.
Press Ctrl+K anywhere to search packages and jump to any page or setting.
Connecting coding agents
What connect writes into each agent, and what you do by hand.
Hexsmith reaches your agent through its MCP server, its hexsmith and hxs skills, and in most agents a hook. Connect writes those entries into the agent's own config files. It only ever touches the entries it owns, and it keeps a sealed copy of every file before changing it.
- Open Agents. Every supported agent is listed, with its state.
- Press Connect on one agent, or Connect all for every agent found.
- Restart the agent (or reload it) so it loads Hexsmith.
| State | Meaning |
| Connected | Every entry is in place and current. |
|---|
| Needs repair | Something Hexsmith wrote is missing or out of date, for example after the agent rewrote its settings. Press Repair. Hexsmith also repairs connected agents by itself when the app starts. |
|---|
| Not connected | The agent is installed, but Hexsmith isn't registered with it. |
|---|
| Not installed | Hexsmith didn't find the agent on this machine. |
| Agent | What Hexsmith adds | By hand |
| Claude Code | The Hexsmith plugin: MCP server, skills, /hexsmith:new, /hexsmith:status, the reminder and the write guard | Run /reload-plugins or start a new session |
|---|
| OpenAI Codex (CLI, IDE, ChatGPT desktop) | MCP server (tools pre-approved), skills, reminder hook, write guard | Open /hooks in Codex once and trust the Hexsmith hook |
|---|
| Google Antigravity | MCP server, skills, reminder hook, write guard | Restart Antigravity |
|---|
| GitHub Copilot (CLI, VS Code) | MCP server, skills, write guard (CLI), prompt files | VS Code asks once to trust the server |
|---|
| Cursor | MCP server, skills, session reminder | Cursor CLI only: cursor-agent mcp enable hexsmith |
|---|
| Gemini CLI, OpenCode, Kilo Code, Cline, Windsurf / Devin, Kiro | MCP server and skills; hooks or guard plugins where the agent supports them | Restart the agent |
The reminder tells the agent, inside a Hexsmith project, to work through Hexsmith's tools. The write guard stops the agent's own file and shell tools from editing or deleting .hexsmith/ or the Hexsmith home.
Disconnect removes exactly what Hexsmith added. The copies taken before each change are in Vault & backups, where any one can be put back.
hxs connect # status of every agent
hxs connect --all # connect every agent found (--dry-run to preview)
hxs connect codex # one agent
hxs disconnect codex # remove it again
In the app: Agents
Projects
Starting one, the console, the timeline, checks.
A project is a folder with a .hexsmith/ folder inside. That's where Hexsmith keeps the project's plan, decisions, timeline and settings. Don't edit it by hand; the write guard stops agents from doing so too.
Starting a project
- In your agent, run
/hexsmith:new (Claude Code) or ask it to start a new Hexsmith project. - The Console opens in this app: pick the kind of project, its stack, the services it uses and its look, step by step. Unfinished setups wait under Projects as drafts.
- Hand it back to the agent. It builds in stages, checkpointing each one.
The Projects page
- Every project on this machine, with filters (needs attention, active this week, archived), sort and a card or list view.
- Open a project for its overview, timeline, decisions, checks, automations and settings.
- Open in editor opens the folder in the editor chosen in Settings, General (VS Code, Cursor, Windsurf…), or the folder itself.
- A project whose folder moved can be pointed at its new place, or forgotten (
hxs projects prune).
Checks: when the agent runs verify, the result is kept with the project. Blocking failures show on Home until fixed.
Approvals: an agent that wants to publish, message people, spend money or do something irreversible asks first. The request shows at the top of Home.
In the app: Projects
Marketplace, armaments and kits
Signed packages for your agent, and sets of them.
Armaments are signed packages your agent can use: connectors to services, providers, playbooks, themes, verifiers (checks), templates, stacks and more. Each one's page says what it does, what it needs, its settings, its help and which edition it belongs to.
- Marketplace: browse by goal or category, filter by kind and edition, or search (press
/). - Installed: what your agent can use now. Rows that need a configuration say so.
- Kits: sets of armaments with one goal. Required parts come with the kit; optional parts are ticked or left out, and parts left out are recorded, not missing. Make a kit builds your own.
- Signed and checked: the installer refuses a package whose signature is wrong or that changed since it was signed.
Editions: Free, Pro and Studio. A package from a higher edition shows its edition and the Plan page shows what each adds. If a licence lapses, paid packages pause; installed free ones keep working.
hxs armaments # installed and available
hxs armaments install <id>
hxs armaments update <id>
hxs armaments remove <id>
In the app: Marketplace
Connections and the vault
Accounts and keys, sealed on this machine.
A connection is an account or key a package uses, such as a payment service or an email provider. Each package lists its ways to connect.
- Open Connections, pick the service, press New configuration.
- The wizard asks for one thing at a time, with a guide to where each value is found.
- Test the connection before saving.
Secrets are sealed in the vault, with a key held by Windows (DPAPI) or the macOS Keychain. Nothing is sent anywhere except to the service itself.
Moving to a new machine
- On the old machine, in Vault & backups, make a recovery file. It's protected by a passphrase you choose.
- On the new machine, install Hexsmith and bring the recovery file in from the same page (or
hxs vault import <file>).
With background checks on (Settings, General), Hexsmith tests saved connections every half hour, even with the app closed, and notifies you when one stops working or a key is about to expire.
In the app: Connections
Automations
Jobs on a schedule and reactions to events.
Automations are jobs on a schedule and reactions to events, defined in each project. The Automations page lists every project's, with its last run, and the ready-made ones packages and kits bring.
Your agent adds them to a project (hexsmith_automation); you can see each one's runs and failures here. A failing automation also raises a notice.
In the app: Automations
Home, Activity and Health
What needs you, what happened, how the machine is.
- Home starts with one sentence about your setup, then Needs attention: approvals, a licence to activate, services to set up or that stopped working, agents not connected, failing checks, plans nearly used up. Each row has its own fix.
- At a glance shows the numbers packages report (usage, checks). Pin a card to the front or hide it.
- Activity is every checkpoint, decision and run across projects, newest first.
- Health runs Hexsmith's own checks (the same as
hxs doctor) and offers a fix for each problem it can solve.
In the app: Home
Updates and your plan
Keeping packages, kits and the app current.
Updates lists new versions of installed packages, kits and the app itself. Update one, or all. When the app has an update ready, a row appears at the bottom of the sidebar.
The Plan page shows your edition, its state (active, expired, revoked), and what each edition adds. Deactivate frees this machine's seat so the licence can move to another.
In the app: Updates
Settings and shortcuts
Appearance, Simple or Dev, language, notifications.
| Section | What's there |
| Appearance | Theme (light, dark, or follow the system), accent colour, density and text size |
|---|
| General | Simple or Dev, where Open in editor goes, notifications, language (English, Hindi, Tamil), background checks |
|---|
| Updates | How the app updates itself |
|---|
| Advanced | The diagnostic log: its level and a button to save it |
|---|
| About | Version, Report a problem, and this Help |
Simple shows plain words and fewer pages, for someone running a business. Dev shows every control. Both run the same engine, so you can switch at any time.
- CtrlK
- Search packages and jump to any page or setting
- Ctrl,
- Settings
- /
- Search the marketplace
- F1
- This Help
- Esc
- Close a dialog, or step back from a package page
The command line
hexsmith and hxs: the same program.
hexsmith and its short name hxs do everything this app does, for scripts and terminals. hxs help lists every command; most take --json.
hxs doctor # check the engine, licence and agents
hxs projects # your projects and their latest activity
hxs activity # recent checkpoints and decisions
hxs connect --all # connect your agents
hxs armaments # installed and available packages
hxs vault export --out <file> # a recovery file for the vault key
hxs settings interface user # Simple (user) or Dev (dev)
hxs logs export --open # a problem report
hxs --version
Set HEXSMITH_HOME to use another home folder (the default is ~/.hexsmith), for example for tests.
Windows and Mac
Installing, and what differs.
Windows
Run the installer. The app goes in your user folder, and hexsmith / hxs go on your PATH. The vault key is held by Windows for your account.
Mac (macOS 11 or later)
- Use the .pkg for your Mac: aarch64 for Apple Silicon (M1 and later), x86_64 for Intel. It installs Hexsmith in Applications and puts
hexsmith and hxs in /usr/local/bin. - If macOS says it can't check the app, open System Settings, Privacy & Security, and press Open Anyway, then open it again.
- The vault key is kept in your Keychain. Shortcuts use ⌘ where Windows uses Ctrl.
Troubleshooting
Common problems, and a problem report.
My agent doesn't use Hexsmith.
Open Agents. If the agent isn't Connected, press Connect or Repair, then restart the agent. In Codex, trust the hook once in /hooks. Inside the project folder, ask it to check the Hexsmith state.
An agent says Needs repair.
Press Repair. It rewrites only Hexsmith's own entries and keeps a copy of the file first. It usually means the agent rewrote its settings or Hexsmith was updated; the app repairs connected agents by itself when it starts.
The marketplace is unreachable.
You're offline or it's blocked. Installed packages keep working; press Retry when you're back online.
My keys can't be opened on a new machine.
Bring in your recovery file in Vault & backups. Without one, set the connections up again.
Hexsmith can't find a project.
Its folder moved or was deleted. On Projects, point it at the new place, or forget it.
macOS won't open Hexsmith.
System Settings, Privacy & Security, Open Anyway. The app isn't notarised by Apple yet.
Sending a problem report
Settings, About, Report a problem saves one .zip to Downloads: Hexsmith's diagnostic log, the machine's facts and the health report. Passwords, keys and tokens are taken out before anything is written. Send the .zip to support. From a terminal: hxs logs export --open.
The log itself is in ~/.hexsmith/logs. Read it with hxs logs show, or have Hexsmith explain a report with hxs logs read <file>.