Codeep on Omarchy
Codeep 3.9.1 or later
The Codeep CLI runs on Omarchy, the Arch Linux and Hyprland setup, like any other terminal tool. Four things fit it in particular: Codeep's colours follow the Omarchy theme, the skills Omarchy links into ~/.agents/skills load, codeep --yolo -- "<prompt>" starts a session without stopping to ask, and Codeep shows up in the bar's Agents panel. The first three arrived in 3.9.0 (use 3.9.1 or later, which fixes typing and redraw problems first seen on Omarchy), the Agents panel in 3.10.0.
tmux send-keys sends them) are sent, pasted text is kept whole, the first-run setup redraws after a theme switch or a resize, and the welcome block shows the folder access you granted.Install
Install Codeep the way Omarchy installs other CLI tools, through mise:
This only writes a small launcher, ~/.local/bin/codeep. The first time you run codeep, the launcher has mise download Codeep's Linux release binary from GitHub (x86_64 or aarch64, whichever matches your machine) and then starts it. Check the version:
github: package shown above. mise on Omarchy refuses npm:codeep. The other install methods are on Installation.Update
mise holds a new release back for a few days after it ships (its minimum release age), so a plain mise upgrade can leave you on the previous version. Omarchy's mup alias updates every mise tool, Codeep included, with that wait turned off:
To update Codeep alone:
API keys
On first run Codeep asks you to pick a provider and paste its API key. On Linux it keeps the key in the Secret Service keyring, which on Omarchy is GNOME Keyring, not in a plain-text file. Each key is its own item, labelled after the provider, for example keyring:api-key-z.ai@codeep.
If no Secret Service is available, or saving to it fails, Codeep keeps the key as plain text in its config file instead, and moves it into the keyring on a later start once the Secret Service is there.
Theme
On Omarchy, the colours Codeep paints itself (the brand red, the greys of the chat, the code colours, the warning orange and the YOLO badge) come from the current Omarchy theme. Switch the theme and an open Codeep session changes with it.
For the theme, Codeep only reads ~/.local/state/omarchy/current/theme/colors.toml and changes nothing in your Omarchy setup. A theme colour too faint to read is darkened or lightened until it reads, so light themes stay legible too.
Turning it off
Open settings and set Follow Omarchy theme to Off to keep Codeep's own colours:
The row is On by default and shown only on Omarchy. Anywhere else, Codeep's colours are unchanged.
Skills
Codeep loads skills from ~/.agents/skills, the directory agent tools share and where Omarchy links its own skills, so Omarchy's skills (such as omarchy and diagnose-crash) are there in every session. When two skills share a name, the project's .codeep/skills wins, then ~/.codeep/skills, then ~/.agents/skills. To list each skill under the directory it came from:
A skill can point the agent at files beside its SKILL.md, such as a guide; Omarchy's skills keep most of their instructions that way. Only files inside the skill's directory can be read: no .., no absolute path, and no link that leads out of it. A skill directory that is itself a link, as Omarchy's are, works. See Skill bundles for the format.
Agents panel
From 3.10.0, Codeep shows up in the Agents panel in Omarchy's bar, beside the agents Omarchy tracks itself: its name, its plan (the provider it used last, for example Z.AI (ZhipuAI)) and its tokens by model. The panel shows its own robot mark for Codeep; it takes marks only from Omarchy's own files.
For that, Codeep writes one file where the panel reads every agent's usage: ~/.local/state/omarchy/agents/usage/codeep.json (under $XDG_STATE_HOME when that is set). It holds all-time counts (prompts, sessions, active days and tokens by model), the dates Codeep was used on and the provider's name. It holds no prompt text and no file paths.
Today's and this week's numbers stay at zero. Codeep can update the file only while it runs, so on a day it does not run they would still show the last day it did. The file is written a couple of seconds after Codeep is first used, then at most once a minute while it works. The panel lists Codeep the next time it refreshes, for example when you open it.
The numbers come from Codeep's usage ledger in ~/.codeep/usage, which it keeps on every platform: one line per model call and one per prompt, with a hash of the session id. No prompt text, no file contents, and Codeep sends it nowhere.
Turning it off
Set Show in Omarchy's Agents panel to Off in settings, and the file is removed at once. The row is On by default and shown only on Omarchy:
Omarchy's own switch hides Codeep too. It replaces the whole providers object, so list any other agent you have switched off in it as well:
After uninstalling Codeep, delete codeep.json by hand to take Codeep out of the panel.
Desktop notifications
From 3.11.0, Codeep can tell you when a run has finished while you were somewhere else. It runs notify-send, so the notification lands wherever your desktop shows them. On Omarchy the shell is the notification daemon, and it is On by default; on other Linux desktops it is Off until you turn it on.
It speaks in three cases:
- A run you started in the terminal ends after 30 seconds or more:
Codeep finished — <task>orCodeep stopped — <task>, and how long it took. Stopped means you stopped it, it paused at a safety limit, it failed, or the model declined. - An approval dialog has waited 10 seconds:
Codeep is waiting for your approval, and the tool's name. - A clarifying question has waited 10 seconds:
Codeep has a question, and the task.
A run started with codeep --yolo -- "<prompt>" notifies the same way, with Agent Mode on. When you are looking at it — on Hyprland, when the focused window is the terminal Codeep runs in — nothing is shown. The server codeep acp runs for an editor never sends one.
~/.local/state/omarchy/notifications/, and a toast is read over a shoulder. So it is made of a fixed phrase, the first five words of what you typed (at most 48 characters, leaving out paths, URLs and file names), how long it took, and the name of a tool — never an answer, a command line or a path.Set Desktop notifications in settings (shown on Linux when notify-send is installed). What you set wins over the default:
Usage, from the shell
codeep usage prints what Codeep has used — today, the last 7 days, all time, and tokens by model — from the local usage ledger in ~/.codeep/usage and nothing else. No network, no API key, any platform:
--json prints one JSON document for scripts and bar widgets (schemaVersion 1). Its keys, in order: generatedAt, today, days (the last N days, zero-filled, by your local calendar day), week, total, models, lastProvider and lastProviderName. With an empty ledger it prints zeros and exits 0.
Live status for bar plugins
A plugin in Omarchy's bar cannot ask Codeep what it is doing, so each Codeep process says it itself, in one small file it owns while it runs: ~/.local/state/codeep/sessions/<pid>.json (under $XDG_STATE_HOME when that is set to an absolute path). It says whether Codeep is idle, working, waiting for an approval or for the answer to a question, with the same short task label as a notification (the first five plain words of what you typed, at most 48 characters, with paths, URLs and file names left out), and the project, provider and model. It holds no answer or command line.
The file is readable by you only, replaced whole through a temporary file, and written at most once a second. It is removed when Codeep ends, also when the terminal is closed on it or it is sent SIGTERM. A Codeep that is killed or crashes leaves its file: a reader should treat a file whose process is not running as stale, and the next Codeep to start removes the files of processes that are gone.
Set Share live status with Omarchy plugins to Off in settings and the file is removed at once. The row is On by default and shown only on Omarchy. Codeep's own bar widget reads these files.
Bar widget
Codeep has a widget for Omarchy's bar, built on the live status files and on codeep usage --json. Its mark sits in the bar and shows whether Codeep is idle, working or waiting for you. A panel shows today's and this week's usage, the sessions that are running, and a field that starts Codeep in a terminal with your prompt.

It needs Omarchy 4, which has the shell's plugin host, and Codeep 3.11.0 or later (3.12.1 for the Ask field). It is written and tested against the Omarchy 4.0.4 package. Install and enable it:
The mark
- No Codeep running: the mark is dim.
- One is running and idle: the mark is normal.
- One is working: the four chevrons light up one after the other, about two steps a second. With the animation off, one chevron stays lit and the other three are dimmed.
- One waits for an approval or has a question: the bar's urgent colour.
Left click opens the panel, right click starts Codeep in a terminal, middle click refreshes. The tooltip says what is going on, and omarchy-shell codeep.agent toggle opens the panel from a key binding.
The Ask field
Type a prompt and press Enter. A terminal opens running codeep --prompt-file <path> in ~/Work (a setting). Your prompt is not on that command line: it is in one private file, and only the file's path is. A new session starts with the file's text as its first message, like starting with a prompt from the shell.
The file is made with mktemp in $XDG_RUNTIME_DIR (/run/user/<uid>, a directory only you can enter), with mode 0600. Codeep removes it as it reads it, and if nothing has, the widget removes it after two minutes, and at once when a step fails. A command line can be read by every other user of the machine, and a file in that directory cannot; it is still not hidden from root or from a process running as you, for the second or two it exists. It needs Codeep 3.12.1 or later: on an older one the widget says so and starts nothing, and your text stays in the field.
The unattended setting is Off by default. When you turn it On, the field starts codeep --yolo --prompt-file <path>, and the panel says so in the urgent colour. If the work folder does not exist, an unattended run is not started, and it never falls back to your home folder with --yolo. A bare launch (right click) is always an ordinary session.
Settings
They live in the widget's entry in ~/.config/omarchy/shell.json:
| Key | Default | What it does |
|---|---|---|
unattended | false | Start the Ask field's prompts with --yolo. A bare launch is never unattended. |
workDir | ~/Work | The folder Codeep starts in. If it is missing, an ordinary run starts in your home folder and an unattended one is refused. |
hideWhenIdle | false | Take the mark off the bar while no Codeep runs; omarchy-shell codeep.agent toggle still opens the panel. |
refreshIntervalSec | 60 | How often usage is read while the panel is open (15 to 3600). |
statusIntervalSec | 3 | How often to look for running Codeep (1 to 60). |
animate | true | Step the mark while Codeep works. Off holds one chevron lit instead. |
codeepPath | The Codeep binary, when it is not on the shell's PATH or in the usual mise and local bin folders. |
What it reads and runs
- It reads the status files in
~/.local/state/codeep/sessions, and/procto check that each one's process is alive and is the Codeep that wrote it. A file that is not a small regular file of yours is never opened. - It runs
codeep --version(also before every Ask) andcodeep usage --json(the latter only on 3.11.0 or later),mktempandrm -ffor the prompt's file, andomarchy-launch-tuiwhen you start Codeep. Every command is an argument list undertimeout, never a shell string, and your prompt is a word of none of them. - It opens no network connection. The one file it writes is the private one an Ask hands its prompt over in, in
$XDG_RUNTIME_DIR; nothing in its own folder or your home folder. The mise launcher script, and a mise shim, are never run in the background: they can install Codeep, so they only run when you ask for Codeep, in a terminal where you see it. A prompt is never handed to the launcher script; right-click the mark to run it once. - Without Codeep, with one older than 3.11.0, or with one older than 3.12.1 for the Ask field, the widget says so in one line, with the command to run.
Remove it with omarchy plugin remove codeep.agent.
Starting Codeep
Start Codeep from a terminal, inside the project you want it to work on:
The first time in a folder, Codeep asks what access to give it and remembers the access you grant for that folder.
Starting with a prompt
For a script or keybinding that opens Codeep unattended, pass the prompt after -- and add --yolo (or hand it over in a file, below):
This starts a new session with the prompt as its first message and does not stop to ask, for that launch only:
- Agent actions run without confirmation, and a vague task gets no clarifying questions.
- The current folder is used as the project with read & write access, so start it in the project folder, not in your home folder.
- Neither the folder access nor these confirmation settings are saved: the next plain
codeepasks as before. The conversation itself is saved as a session like any other. - The status bar shows YOLO.
Some things still ask. Writes the agent makes with its file tools to files that decide what runs later, such as .git/config, git hooks, .codeep/hooks, .codeep/skills, .agents/skills and MCP server lists, are still confirmed, and a workspace's own MCP servers still ask to be trusted the first time. A shell command the agent runs is not checked this way: under --yolo it runs without asking and can write those same files.
-p <prompt> and --prompt <prompt> do the same as -- <prompt>. Everything after -- is the prompt, and a leading / is sent as text, not run as a slash command:
A prompt from a file
--prompt-file <path> (3.12.1) reads the prompt from a file instead, for a launcher that does not want it in the process list: a word on a command line can be read by every other user of the machine through /proc/<pid>/cmdline, and a private file cannot. It does the same as -- <prompt> in every other way, --yolo included, and the Ask field of the bar widget uses it. An environment variable would be private too, but a terminal that runs as a single instance (ghostty, kitty, foot's server) starts its child from its own environment, so it would not arrive.
- The path must be absolute, with no
~, and name a regular file you own, not a symbolic link, that its group and others cannot write, of at most 256 KiB of UTF-8 text. Anything else ends the launch with one line saying why and exit code 1, before a session starts. - Codeep removes the file after reading it, but only when its name is
codeep-prompt-and at least six letters or digits, asmktemp codeep-prompt-XXXXXXXXXXmakes it. Any other file is left alone. - It is one prompt:
-p,--and--prompt-filetogether are an error. - Codeep before 3.12.1 does not know the flag. It ignores it and the path, and starts without a prompt, so check
codeep --versionfirst, as the widget does. - This keeps the prompt out of the process list and nothing else. It is still saved in the session like any other, and its first words name the run in the status file and in notifications.
omarchy agent does not start it. Start it from a terminal as shown above.