Installing Semantix Studio

Semantix Studio ships as one file — an AppImage. There is no installer, no package to add to your system, no account to create before you can open it, and nothing that needs root.

You download it, mark it executable, and run it.

What you need#

Semantix Studio is built and tested on Linux. That is the only platform it runs on today.

macOS and Windows are not supported. They are not quietly broken or half-working — they are not built. When they are real, they will appear on the download page, and not before.

Installing it#

Three commands, from wherever you put your downloads:

# 1. make it executable
chmod +x Semantix-0.9.2-x86_64.AppImage

# 2. run it
./Semantix-0.9.2-x86_64.AppImage

That's the whole installation. The file you downloaded is the program — it does not unpack itself into your system, register services, or write anything outside your home directory.

If you'd like it in your menu like a normal application, move it somewhere on your PATH first:

mkdir -p ~/.local/bin
mv Semantix-0.9.2-x86_64.AppImage ~/.local/bin/semantix
chmod +x ~/.local/bin/semantix
semantix

What's inside the file#

The AppImage is about 119 MB because it carries its own engine room. Four things ride inside:

• The Semantix shell — the IDE you actually look at: editor, search, the living graph canvas.
• semantix-server — the local engine. Parses your code into symbols, references and callers, keeps the graph alive, and answers the editor's questions. This is the piece that makes the index work, and it runs on your machine.
• semantix-tasksd — the scheduler daemon. This is what lets a task run at 4am, or keep running after you close the window. See When Semantix is closed.
• semantix-trig — the trigger watcher, for tasks that fire on an event rather than a clock.

They start and stop with the app. You do not install, configure, or run any of them yourself.

First run#

Open a folder, and Semantix indexes it.

The first index of a large project takes a moment — it is parsing every file, not scanning names. After that it keeps itself current as you edit, and only re-reads files that actually changed.

You can use the editor, the search and the graph immediately. No network is involved in any of it, and no key is needed. If you never run an agent, Semantix never talks to anyone.

Adding a model key#

Agents need a model, and a model needs your key. You add it inside the app, in settings, as a custom model — a name, a base URL, the model id, and your key.

Semantix stores it here:

~/.semantix/USER/custom-models.json

Where Semantix keeps things#

Everything Semantix writes lives under one directory:

~/.semantix/
├── USER/
│   └── custom-models.json     your model settings and keys
├── WORKSPACE/
│   └── <project>/index/       the index for one project — symbols, refs, graph
└── flows/                     agent flows you've saved

Your projects are not touched. The index is kept beside Semantix, not inside your repository, so there is nothing new to add to .gitignore.

Updating#

There is no auto-updater. Semantix will not reach out, check a version, or replace itself while you aren't looking.

A new version is a new download: get the new AppImage, and use it instead of the old one. If you put it on your PATH as above, overwrite that file.

Your index, settings and flows are in ~/.semantix/ and are untouched by this.

Uninstalling#

# the program
rm ~/.local/bin/semantix        # or wherever you put the AppImage

# everything it ever wrote — index, settings, keys, saved flows
rm -rf ~/.semantix

That is genuinely all of it. Nothing was installed into your system, so there is nothing left to find. Deleting ~/.semantix also deletes your saved model keys and flows, so if you only want to free the disk that indexes take, delete ~/.semantix/WORKSPACE/ and leave the rest — Semantix will rebuild an index the next time you open that project.

If something goes wrong#

It won't start, and the terminal mentions FUSE. Your distro is missing FUSE. Install it (fuse or libfuse2 depending on the distro), or run the AppImage extracted: ./Semantix-0.9.2-x86_64.AppImage --appimage-extract-and-run.

It won't start, and nothing is printed. Run it from a terminal rather than a file manager — the AppImage prints its startup errors to stdout, and a double-click throws them away.

The graph or search is empty on a project you just opened. The first index is still running. Large projects take longer; it is parsing, not listing.