Mac or Linux.
A Mac (Apple Silicon or Intel, macOS 12 or newer) or a Debian or Ubuntu Linux machine. There is no Windows version yet.
Getting started
From download to your first saved draft.
Seven steps. You describe your business once, Alacrán drafts what it learned, you read it and approve it, and it is saved as plain files on your own computer. Everything in Alacrán follows the same four beats: You ask, Alacrán drafts, You approve, It's saved.
Before you start
Three things to have ready.
A paid Claude plan.
Alacrán starts with Claude Code, which needs a paid Claude plan (Pro is about $20 a month). No plan yet? You can still explore without AI and connect it later.
One or two sentences.
That is all the first question needs. You can add detail later, and Alacrán never fills a gap with a guess.
Download and open Alacrán.
Use the buttons above. On a Mac, open the .dmg and drag Alacrán into Applications. On Debian or Ubuntu, install the .deb and launch Alacrán from your applications menu.
sudo apt install ./Alacran.debMac only, once: the build is not notarized by Apple, so macOS may say Alacrán is damaged. It is not. Run this in Terminal before the first launch. It clears the quarantine flag macOS puts on anything downloaded from the internet.
xattr -cr "/Applications/Alacran.app"There is no Alacrán account, hosted database or licence key. Later updates come through the app's own Update & Restart button, and the Mac command is not needed again.
Pick a goal and read the trust note.
The first screen, Welcome to Alacrán, has four short steps: Goal, Trust, AI and Create. On Goal, choose the outcome closest to your work: Run my business, Build software, Win customers or Grow my audience.
The Trust step says what to expect. Your company memory stays as readable files on this computer. Your AI sees what it reads. Changes wait for your OK.
The goal only picks your starting workspace. You can change everything later.
Connect the AI that does the work.
On the AI step, press the button to install Claude Code, then sign in with your Claude account. Come back and press Re-check. Alacrán checks your computer and tells you what is missing.
Claude Code needs a paid Claude plan. Not ready? Choose Explore without AI. You can add company details and records now, and connect your AI from Home when you want to ask questions or prepare drafts.
Create your company.
Give it a name, for example Ama's Catering. Alacrán creates a folder for it inside an Alacran folder in your home folder. It also keeps a full history, so any change can be seen and undone, and sets up ready-made jobs: a daily summary, a place to record decisions, and look-backs. The starter pack follows the goal you chose.
Already have a project folder? Adding a company can also use an existing folder or restore one from GitHub. A folder added as an existing project gets no guided steps.
Tell Alacrán about your business.
You land on Home, which leads with one next step: Start here, Tell Alacrán about your business. It asks four short questions, then a last screen called Check & save.
What does your business do, and for whom? A sentence or two in your own words is plenty. For example: We cater events for companies in Accra: office lunches, launches and weddings.
Who is involved? Your customers, your team, your suppliers: anyone the business depends on.
How work flows. Where a job comes from, what you do with it, and what the customer gets at the end.
What takes up most of your time right now? The thing you wish you could hand off. Alacrán looks for ways to help with it first.
On Check & save you have two choices. Let Alacrán write it up has your AI turn the answers into a draft that waits in Approvals. Save my answers as they are keeps your own words straight away, with no AI.
If your AI is not connected yet, Let Alacrán write it up is switched off and links to the AI setup. Closing the window in the middle keeps your answers.
Read the draft and approve it.
Approvals holds everything Alacrán has drafted. Open the draft and read the preview. Choose Review & approve to keep it, Ask for changes to send it back with your note, or Discard to drop it. Nothing is saved until you approve.
After your first approval, Home and Approvals tell you it is saved. That is the whole loop: you asked, Alacrán drafted, you approved, and it is kept in your company's files.
A company profile is marked High risk. That is expected: it holds your core facts, so it deserves a careful read. Today its preview appears as plain text in a file format called YAML, lines like name: value, rather than as a summary.
Ask your company a question.
Open Ask and try: What needs my attention today? Your AI starts from the files you just saved instead of a blank prompt. Ask answers from your company's files and does not change anything. When Alacrán needs to change a file, it drafts the change and it comes to Approvals.
Alacrán's agents are told to stop and ask before money, contracts, publishing, deletion or access changes, so those always reach you first.
For AI agents
Reading a company Alacrán made.
If you are an AI agent working in a company folder that Alacrán created, this is the order to read it in and the rules to follow. This page is also available as Markdown at /getting-started.md, and every page is indexed at /llms.txt.
In the company folder
Read these first. They are plain files, and they are the source of truth.
AGENTS.md
The working agreement, at the root of the folder. Read it first. CLAUDE.md is only a pointer to it.
definitions/ontology/company.yaml
The facts every other file assumes, written from the wizard answers. An unknown value is marked <<TODO>>. Never replace it with a plausible guess.
docs/decisions/
One file per decision, named YYYY-MM-DD-slug.md, with the reasoning and the rejected options.
notes/ and records/
Notes are working material. Records are operational data an agent maintains and a human may edit.
The gate
Stop and ask a human before you spend or quote money, create an obligation, delete or overwrite data, publish anything outside the company, or change who has access. Draft the finished work, show it, and wait.
If something feels wrong
Common first-day problems.
macOS says Alacrán is damaged and can't be opened.
It is not damaged. The download is not notarized, so macOS quarantines it. Run xattr -cr "/Applications/Alacran.app" in Terminal once, then open it again.
Alacrán says my AI is installed but not signed in.
Sign in to Claude Code with your Claude account, then press Re-check. Claude Code needs a paid Claude plan.
My first draft finished with nothing to review.
Your AI may have been busy, signed out or out of usage. Home says so, shows what happened behind a fold, and lets you try again.
I do not want the guide on Home.
Choose I know how this works. Home hides the guide and it does not come back.
Can I use Alacrán on Windows?
Not yet. Alacrán is available for Mac and for Debian and Ubuntu Linux.
Where are my files, and what if I stop using Alacrán?
They are in the Alacran folder in your home folder, as plain Markdown and YAML with git history. Removing the app leaves your company's files where they are.
Keep going
Where to go next.
How to use Alacrán.
The same path in six short steps, plus recovery tips. Read how to use
How Alacrán works.
Durable memory, the gate on consequential actions, and four plain folders. Read the docs
Connect what you already use.
Chats, email, calendar and more, always read-only. See connections