AgentWitch Docs
Browse docs

Quick start

This page takes you from the AgentWitch home page to your first free token check on your own computer. You create an account, put the app on your computer, and scan a project. Plan on a few minutes, plus the time your Mac needs to finish setup.

#Before you start

  • A Mac (macOS 13 or newer; the Download page says Apple silicon, M1 and later) or a Linux desktop. On Windows, AgentWitch runs inside WSL. Install and connect covers the details.
  • At least one coding assistant you already use on a project, such as Claude Code, Codex, Cursor or Gemini CLI. AgentWitch finds your projects from the folders those tools remember, so there is something to check.
  • Nothing to pay. The token check and the download are free.

AgentWitch cannot run on a phone, so a download button there would do nothing. Instead the home page shows On a phone? Send the install link to your Mac.

  1. Type your email into Your email.
  2. Click Send me the link. You see "Sent. Open it on your Mac when you are there."
  3. On your Mac, open the email "Your AgentWitch install link" and click Open the Download page.

The email repeats the three steps: download the Mac app and open it, sign in once to connect the computer, and pick a project folder. You can ask for up to three emails per hour for one address. If it fails, the page says "Could not send right now. Try again in a minute." Wait a minute and try again.

#Step 1: Create your account

  1. Open www.agentwitch.com on the computer you want to check.
  2. Click Run a free token check. The top bar also has Free token check.
  3. In Create your free account, click Continue with Google. Or type your email, tick I agree to the Terms and Privacy policy, and click Create account.
  4. If you used email, open the message and click the link. If it is not there, check spam. Resend is available after 30 seconds.

If you see "We are extending our capacity", AgentWitch is at capacity and puts new accounts on a waiting list. You can register now. You download and connect your computer once you are added.

Account and sign-in lists every way to sign in.

#Step 2: Put the app on your computer

After sign-in you land on Home. A new account shows Set up AgentWitch with two steps: Create your account (done) and Download the app.

  1. Click Download for macOS (or the button for Linux).
  2. Open the downloaded file. On a Mac, drag AgentWitch into Applications, then open it from there. If macOS asks, choose Open.
  3. Wait while the app sets itself up. It shows Checking this computer, Downloading the connection, Installing support for assistant tools and Checking everything works. You can close the window. Setup keeps going.
  4. Look for the wand icon at the top right of the menu bar. There is no Dock icon.
  5. Back on Home, click I’ve installed it. When the computer is linked, Set up AgentWitch gives way to your project list.

If Home says "Not connected yet", click Connect with the app. The app opens your browser. If you are already signed in, the browser hands you straight back.

If the app says "Trial on this Mac". A fresh Mac can set itself up with no account, so you can try it first. The Computer page then shows Trial on this Mac and a button, Create an account. Click it, finish in the browser, and your projects and history move to your account. If your account already has computers or projects, the app asks whether to keep your account and discard the trial. Project folders and files stay on the computer either way.

#Step 3: Run the token check

About a minute after the app starts, it adds the projects your coding tools remember. It looks again every half hour. The Mac app tells you when it sets one up.

  1. On Home, find your project in the list. The Setup tokens per run column says Not scanned yet.
  2. Click Scan token leaks. The button changes to Scanning….
  3. Read the result in the same row:
    • Lean and No leaks mean your setup is small. Under about 250 tokens is counted as lean.
    • A number such as ≈12k with "up to, could go every run" means setup loads on every model call and part of it can go. Click Fix token leaks.
  4. To see the details, open the project and go to Health, then Token leaks. It lists places to trim, biggest first. Click one to see the problem and the fix. Token check and savings explains the numbers and the fixes.

The scan reads rules, the skill list and MCP tools on your computer. Numbers are estimates. After a scan, Scan now comes back after 15 minutes.

If the project is not on the computer in front of you, the button opens the Token leaks page instead. If a page says "Scan runs on this computer. Open this page in a browser on the computer where AgentWitch is running.", do that.

No project in the list? Click + New project, pick the folder or paste its path, and click Create project. The button needs a connected computer.

#Step 4: Hand over a first task (optional)

You do not need a task to get value. Work in your assistant as usual, and AgentWitch drafts skills from what you repeat. When you want to hand something over:

  1. Open the project.
  2. Click New task, write what you need, and send it.
  3. Watch the result under History.

#Guided setup page

www.agentwitch.com/onboarding/machine walks through four steps: Computer, AI tool, Project and Done. Each step has Skip for now. The AI tool step shows Ready when an assistant is installed and signed in. Home does not link to this page today, and it sends you back to Home if you already have a project.

#When it does not work

  • Home stays on "Download the app". Open AgentWitch from Applications, then click I’ve installed it again.
  • Setup stops with "Setup didn't finish". Click Retry setup. If it fails again, click Repair. Install and connect has more.
  • The scan button is missing or says it cannot reach your computer. Check that the app is running. Its icon is in the menu bar.

#Query aliases

  • AgentWitch quick start
  • run a free token check
  • install AgentWitch on my Mac from my phone
  • first token scan
  • how to get started with AgentWitch