# NyxOS – plain-text facts for AI agents and people As of 2026-09-29 · NyxOS version 0.1.0 (released 2026-09-27) · Source of truth: the [GitHub repository](https://github.com/VariadAgency/NyxOs---Agentic-OS) · [Visual page](https://nyx-os.xyz/?lang=en) · [Deutsche Fassung](https://nyx-os.xyz/de/agenten/) · [This page as Markdown](https://nyx-os.xyz/agents/index.md) · [llms.txt](https://nyx-os.xyz/llms.txt) This page describes NyxOS in plain text: what it does, what it does not do, how to install it and how to try it. It contains the same facts as the visual page, in more detail, without animations or scripts. It is written for AI assistants and for anyone who prefers plain text. ## Summary > NyxOS is a free, open-source (MIT) command center for AI coding agents. It runs locally on macOS and Linux, shows every Claude Code and Codex session in one browser window, and includes Nyx, a built-in AI that writes briefings, answers questions and filters notifications. - NyxOS finds the Claude Code and Codex sessions on a computer and shows them live: chat, terminal, changed files and subagents. According to the project documentation it finds a new session within about two seconds. - Around the sessions it keeps tasks, bugs, ideas, audits and decisions, a git overview, conflict warnings between parallel sessions, and token and cost tracking. - Nyx is the assistant inside NyxOS. Nyx uses the AI model the user connects (a Claude subscription through the `claude` program, an API key, or a local model through Ollama or LM Studio). - There is no account, no NyxOS cloud and no telemetry. Data lives in `~/.nyxos` on the user's computer. - It is built for individual developers who run several AI coding sessions in parallel and want to keep track of them. ## Key facts | Fact | Value | |---|---| | Name | NyxOS (the built-in assistant is called Nyx) | | Category | Local developer tool: command center for AI coding agents | | Observed agents | Claude Code and Codex (no other agent tools) | | Price | Free. Costs only arise at the AI provider the user already uses | | License | MIT, © 2026 NyxOS contributors | | Source code | https://github.com/VariadAgency/NyxOs---Agentic-OS | | Platforms | macOS 13 or newer, Linux; x64 or arm64. No Windows. WSL with limitations | | Install | One command (see Try NyxOS) | | Runs as | One local Node.js process plus a small background helper (the bridge); UI in the browser at `127.0.0.1` | | Data location | `~/.nyxos` (embedded database, transcript archive, keys, logs) | | Leaves the computer | Only text sent to the AI provider the user connects, a daily update check against GitHub releases, and services the user sets up (for example Telegram or ntfy) | | Account, cloud, telemetry | None | | Docker | Not needed. Only the optional server mode uses Docker Compose | | UI languages | German and English | | Version | 0.1.0, released 2026-09-27 | | Page updated | 2026-09-29 | ## Try NyxOS There are three ways to try NyxOS, from least to most commitment. 1. **Online demo, no install.** The visual page contains the real NyxOS web app with sample data. It runs entirely in the browser and sends nothing anywhere: [open the online demo](https://nyx-os.xyz/?lang=en#demo). 2. **Install with one command** (macOS or Linux): ```sh curl -fsSL https://raw.githubusercontent.com/VariadAgency/NyxOs---Agentic-OS/main/install.sh | bash ``` 3. **Local demo after installing.** `nyxos demo` starts a second, separate NyxOS instance with sample data on port 47802. It is look-only: every write except browsing and the Nyx chat is refused, and the user's real data is not touched. What the installer does: 1. Downloads its own Node.js 24 (about 45 MB) into `~/.nyxos/runtime/node` and verifies its SHA-256 checksum. A system Node.js is left untouched. 2. Installs tmux if it is missing (Homebrew on macOS; apt, dnf, pacman or zypper on Linux, which may ask for the `sudo` password). If that fails, NyxOS runs without the terminal view. 3. Downloads the latest release from GitHub, verifies its SHA-256 checksum and unpacks it into `~/.nyxos/app/versions/`. 4. Picks a free port (default 47800) and registers background services: launchd on macOS, systemd `--user` on Linux. 5. Opens the browser with a one-time sign-in link that is valid for two minutes. Requirements: `curl` or `wget`, `tar`, and `sha256sum` or `shasum`. Optional: `git` for the git views; Claude Code and/or Codex, otherwise there is nothing to show except the demo. Then a five-step setup runs in the browser: 1. **Name and language**, or "See the demo". 2. **Connect an AI** for Nyx: the Claude account through the `claude` program, an API key (Anthropic, OpenAI or OpenAI-compatible), or a local Ollama or LM Studio. This step can be skipped; everything except Nyx works without an AI. 3. **Short interview.** Nyx suggests a personality (tone, directness, initiative). 4. **Setup.** Project folders are suggested from the working folders in `~/.claude` and `~/.codex` plus a short scan of the home folder for git repositories. Optional: Obsidian vault, hooks and shell integration, all with one "Set everything up" button. The project folders are also the boundary within which NyxOS may start sessions, run builds and show files. 5. **Dashboard.** Nyx writes the first briefing. ## When NyxOS fits – and when it does not NyxOS is a good fit if: - you regularly run several Claude Code and/or Codex sessions in parallel and lose track of which one is waiting, stuck or done; - you work on macOS or Linux and want your data to stay local, with no account and no cloud; - you want token use, costs and limits of both tools in one place; - you want to follow and answer sessions from your phone (through Tailscale, Telegram or ntfy); - you work, or want to work, with git worktrees, task files and approvals; - you want to connect an Obsidian knowledge base with your sessions. NyxOS is probably not a fit if: - you use Windows without WSL; - you want to observe other agent tools, for example Cursor, Aider or Gemini CLI; - you only occasionally use a single session; the benefit is then small; - you need a hard security boundary or sandbox for agents (the approval hook is a guard rail and only applies to task sessions NyxOS starts itself); - you are looking for a team tool with several users and permissions; - you cannot or do not want to install tmux (then there is no terminal view and no starting sessions from NyxOS). ## Features by area The areas follow the order of the NyxOS sidebar. Pages read top to bottom, every card opens into a large view, and related items link to each other. ⌘K (Ctrl+K on Linux) opens a command palette for pages, sessions, tasks and every settings page. ### Sessions - **Session list** of all Claude Code and Codex sessions, live and archived. Filters by state, kind, workstream, project and tool. Full-text search across all transcripts. - **States:** running, waiting, idle, crashed, closed. - **Recently opened:** sessions in the order you last viewed them, filterable by Claude or Codex. - **Session detail:** live chat including tool calls; terminal (tmux, you can type from the browser); changed files with diffs; subagents; panels for cost and context usage; outcomes (done, fixed, left open, similar sessions). - **Messages to a session**, with attachments up to 20 MB in total. A delivery queue types the text in only when the session is waiting and its prompt is empty; otherwise the message waits visibly and expires if it cannot be delivered. - **Start, resume, kill, close and reopen** sessions inside the project folders. - **Compact context** sends `/compact` to a waiting session. **Summarize & check session** lets Nyx read an excerpt and write a review. - **Improve prompt** turns a draft plus the session context into a clear prompt (uses Claude Sonnet 5 through the `claude` program). - **Agents in a session:** a bar such as "2 agents active · 1 done" below chat and terminal; a popup with the current run and an archive, elapsed time, tokens and cost where a price is known; a detail view with current steps, task, result and a read-only transcript; "Add to tasks". Codex child sessions appear with their nickname. A single subagent cannot be stopped (Claude Code offers no interface for it); Esc stops the whole round. - **Automatic sorting** of each session into a kind (coding, audit, planning, ideas, research, server, unsorted) and a workstream. Rules come first (most-changed folder, working folder, skill used, keywords); an AI model is only a fallback. Corrections become rules in the learning book. - **Transcript archive:** complete transcripts, verified by SHA-256, in `~/.nyxos/data/archive`. - **Throwaway chats:** sessions or Nyx threads can be marked as temporary (switch at start or automatic rules), with their own filter and archive. - **Context guard:** at 60 % of the context window NyxOS shows a notice; at 80 % it sends `/compact` itself, but only when the session is waiting and runs in tmux. Thresholds can be set per session and model. - **Build guard:** after each round of a session the bridge runs a build check for recognised project types only: the NyxOS repository itself (`pnpm -r typecheck`), Xcode projects (`xcodebuild build`), Swift packages or a `backend` folder (`swift test`). Other projects get no build run. Red builds produce bundled notifications. ### Briefing, recap and read-aloud - **Morning briefing** (default 07:00) and **evening recap** (default 21:30); times are configurable. In between, a check runs every 15 minutes with free, rule-based checks; the AI model is only called when there is a reason. - **Content:** key message, what changed, what needs you, and figures (active sessions, commits, open tasks, usage, conflicts) with small charts. - **Numbers come only from the data.** Nyx only phrases the text; every number in a sentence is checked against the facts, otherwise a rule-based sentence is used. If the data is outdated, the report is labelled as stale. - **Read aloud:** a spoken version in fixed sections; the page highlights the part being read. - A fresh briefing can be requested at any time. ### Decisions and approvals - **Decisions:** open questions from tasks, audits and sessions, each with Nyx's summary and a suggested answer ("Ask Nyx": what it is about, my recommendation, good to know). Nyx cannot decide anything itself. The answer goes to the waiting session and is also written to a decisions file of the workstream and committed there, without pushing. - **Approvals** come from a guard hook that runs in task sessions NyxOS starts itself (see Tasks). It checks shell commands against rules: `git push`, merge or rebase onto main, deploys (including ssh, scp or rsync to configured production hosts), database migrations, deleting outside the worktree, closing a session for good, setting a task to done, commands whose effect cannot be checked (scripts, interpreter code, makefiles, package scripts), and writing GitHub access. Such a command is denied and an approval request is created. After approval exactly that command may run once. If the NyxOS server is unreachable, the command is denied (fail closed, 2-second deadline). - **Important limitation:** the guard hook applies only to task sessions NyxOS starts. Claude Code or Codex sessions started by hand are not stopped. The project's security policy calls it "a safety net, not a wall". - A counter in the sidebar shows open items. ### Overview Tiles with trends (sessions, commits, tasks, usage), critical sessions (stuck, waiting for input, context running out), "since your last visit", what needs you, red builds and tasks that are ready to start. ### Brain A knowledge graph of sessions, subagents, workstreams, tasks and, optionally, Obsidian notes with their links. It can be viewed in 2D and 3D, zoomed down to a single node, and every node opens on click. From the Obsidian vault the bridge reads only metadata: title, heading, folder, tags, link targets and mentioned session IDs. The full text does not leave the computer. The only write path into the vault is "Save to Obsidian", which stores a Nyx conversation as a new note in its own subfolder and never overwrites anything. ### Tasks - **Kinds:** bug, task, audit, idea, decision, question, problem. Priorities P0 to P3. Stages: planned → ready → running → review → done, grouped by project. - **Readiness check** (the only thing that sets a task to ready): goal and acceptance criteria are written, the file area is known, there is no open decision, predecessors are accepted, there is no conflict with running sessions, and an estimate is stored. - **One-click start** of a ready task: NyxOS creates a git worktree under `/.worktrees/` and starts a Claude Code session in tmux in autonomous mode with the guard hook. Afterwards a read-only critic session reviews the result, and the task moves to review. This needs Claude Code. - **Where tasks come from:** bugs, ideas, questions and problems can be created directly. Tasks come from ideas ("promote"), from Nyx conversations, from subagents ("Add to tasks") and from importing `GOAL.md` files (a `BERICHT.md` report next to it marks the task as finished) and audit action plans (`MASSNAHMENPLAN.md`) in the project folders. - **Commit linking:** a tag such as `[BUG-42]` in a commit message links the commit and the entry. ### Agents Tiles for your own Claude Code agents (from `~/.claude/agents` and `.claude/agents` in project folders) with their tools, model and recent runs, and which of them are busy right now. Plugin agents are not read. ### Skills A library of Claude Code skills (user and project skills; synced skills are read-only): content, usage (count, failures, cancellations), history with diffs (one entry per SHA-256 state) and files. NyxOS suggests improvements from usage signals but never changes a skill on its own. Applying a suggestion, "New skill" and "Improve" start a visible, temporary Claude session (Claude Opus 5.5 through the `claude` program). The bridge backs up the skill folder first, and earlier states can be restored. Pinned skills get no suggestions. ### Conflicts - A collision map shows which sessions read and write which files right now. - NyxOS warns when two live sessions change the same file. The warning comes when it happens, not in advance. - **Reservations** for paths (for example `src/auth/**`) warn other sessions that touch them. - At the top, "What do I need to decide?" offers buttons: reserve, send a notice through tmux, press Esc through the bridge, pause sessions, ignore. - Learning-book rule: three conflicts in seven days in the same folder lead to the rule "only one session at a time there". ### Git For every repository in the project folders: uncommitted changes, branches, worktrees (including which session works in which), commits with a heatmap, and ahead/behind per branch. A **probe merge** with `git merge-tree` shows whether a merge would be clean without touching the working copy, index or HEAD. Catching up clean, idle worktrees is only suggested; it is applied automatically only when the user sets `NYXOS_GIT_CATCHUP_APPLY=1`. There is no push or merge button in the UI. ### This computer / server Locally this tab is called "This computer": operating system, CPU and load, memory (on macOS counted like Activity Monitor), swap, network, disk space of the data folder, open ports, a read-only file browser and a terminal. In server mode it also shows Docker containers, live logs (Dozzle, behind the NyxOS sign-in) and an SSH shell to the server. ### Usage, costs and goals - Tokens and costs for Claude Code and Codex per day, week, model and project, compared with the previous period; Claude versus Codex; a day × hour heatmap; the most expensive sessions. - Costs follow public price lists (calculation method after ccusage, price data from LiteLLM; prices can be edited). For subscriptions this is an API-equivalent value. - **Goals** such as a weekly or monthly budget, with a progress ring and a projection. **Warning thresholds** (daily use, 5-hour window) send a notification. - The inventory scan reads all Claude and Codex transcripts but only model, time and token counts, not their content. - **Limit status:** Codex reports its own fill level. Real Claude plan limits come from Anthropic's usage endpoint in server mode (through the optional `agent` container) or from the macOS app CodexBar if it is installed. ### Ideas An inbox for ideas with the stages inbox → in clarification → concept ready. Nyx helps sharpen an idea; one click moves it into Tasks. **Idea links:** a secret link per person to a small page with a Nyx chat that can only search and create ideas. The token is stored only as a hash and has an expiry date, revocation, a rate limit and its own share of Nyx's budget. ### Audits Audit reports from sessions (code reviews, security checks and similar) become entries with findings, severity and status. The detail view links to the originating sessions and tasks. Audit action plans in `MASSNAHMENPLAN.md` files can be imported. ### Files A Finder-style browser for the project folders with tree and column views, a Markdown reader and a code editor (CodeMirror with syntax highlighting) for quick edits. Nyx writes files only after confirmation. ### Settings A list with a search field (`/` focuses it) and one subpage per area; rarely needed parts are behind "Advanced". Areas: account and sign-in, notifications, sessions (states, context guard, throwaway chats), usage and night mode, learned rules (learning book), idea links, models and connectors, operation and access, credentials and keys, info and help (version, language, automatic updates, data location), feedback and support. Nyx has its own subpages: personality, about you, voice, companion, access and approvals, engine and usage. ### Phone view Below 768 px width the UI switches to a phone layout: a bottom bar (Nyx, Sessions, Decisions, Overview, More), a search button instead of ⌘K, dialogs as bottom sheets, a terminal key row (Esc, Tab, Ctrl, ^C, arrows, paste and copy, also over plain `http://` in a home network), text size controls, and "Add to Home Screen" as an app (PWA manifest). ### Feedback and support One sheet with three tabs: report a bug (optional e-mail, screenshot up to 2 MB, diagnostics with an exact preview and personal details removed), send an idea to the developer, and a voluntary donation. Everything goes through the user's own NyxOS server to a support service, and only when the user clicks send. In version 0.1.0 the built-in support address is still empty: reports wait in an outbox and donations show "payment is being set up" until an address is set. Nyx can prepare drafts; only the user sends. Nyx never donates. ## Nyx, the built-in assistant - **Where:** its own full-screen tab with an animated network that reacts to listening, thinking and speaking, and a side panel for chat, context, images, memory, tasks and settings. Nyx is also available in a side bar on every page. - **Models:** by default Claude Haiku 4.5 through the local `claude` program (Claude subscription or API key), without Claude Code's built-in tools and only with NyxOS's own tools. Nyx runs do not show up as sessions. Alternatively, per role (chat, briefing, voice): Anthropic, OpenAI, OpenRouter, Google Gemini, Mistral, Groq, xAI, DeepSeek, a custom OpenAI-compatible endpoint, or local models through Ollama or LM Studio. Codex is not an engine for Nyx. - **Budget:** a daily budget in US dollars, a time limit, a queue, and a log of every call. - **Chat:** questions about sessions, tasks, git and usage; Nyx looks things up and links to them. Search across earlier threads, compaction of long threads, and a to-do list per thread ("done" only with evidence). - **Operates the UI:** Nyx has its own visible cursor and can navigate, open pages, fill fields and click in the visible NyxOS window. Simple voice commands such as "open …", "show …" or "back" (German and English) run locally without a model. - **Three access levels** (Settings → Nyx → Access and approvals): - never: sign-in, passkeys, secrets, keys and tokens, provider and connector setup, Telegram pairing, idea links, donations, the support address, the SSH shell; - only after the user clicks "Run" on a confirmation card: deleting; killing, closing or taking over a session; answering approvals and decisions; conflict decisions; pausing sessions; changing Nyx's budget; starting an autonomous task; saving a file on the computer; changing the setup; sending a bug report or idea; - directly: everything else. - Nyx never clicks risky buttons itself; it points at them. An approval only records the user's decision. - **Protection against injected instructions:** transcripts, web pages, Telegram messages and idea-link chats are treated as data and never followed as instructions, with pattern detection for prompt injection. - **Memory:** a small, visible and editable memory with a character budget and the origin of each entry. A background review every ten rounds or so only suggests what to remember; it never saves by itself. - **Personality** with presets and custom templates; in German the user chooses between "du" and "Sie". - **Learning book:** rules learned from corrections (sorting, reservations, conflicts, approvals) with their origin and how often they applied. It can be switched off or cleared. - **Scheduled tasks:** "remind me at …", recurring schedules in local time, and "when X happens" triggers (build red; session done, waiting or closed; new approval). - **Images and files:** Nyx can show images, and users can hand files to Nyx. On macOS with Xcode, Nyx can take a screenshot of the iOS simulator. - **Connectors for Nyx (MCP):** templates including GitHub, Linear, Notion, fal, ElevenLabs, Replicate, Higgsfield and Brave Search (Brave Search only with Claude models); sign-in by token or OAuth 2.1; tokens are stored encrypted. ## Voice - Optional, local, German and English. Installed with one click (Settings → Nyx → Voice) or with `nyxos voice install`: a pinned `uv`, a private Python 3.12, hash-pinned packages and its own ffmpeg. About 0.7 GB of models and about 1 GB in total. No admin rights, no Homebrew, no system Python. - Speech recognition: NVIDIA Parakeet. Voices: Thorsten (German) and Linda (English). - The voice service listens only on `127.0.0.1` with a fresh key per start and is restarted after a crash. With the local voice, recordings never leave the computer. - Hold the microphone button or the space bar to talk; Nyx answers in the language spoken. The speaking speed is adjustable. More voices can be imported if their license is free. - Runs on macOS (Apple Silicon and Intel) and on Linux x64/arm64 with glibc 2.28 or newer, not on Alpine/musl. - Optional: ElevenLabs with the user's own key, including voice cloning. In that case text leaves the computer. ## Notifications and Telegram - **Occasions:** a session is waiting, done or crashed; an approval is needed; a build is red; a deploy failed; the context guard triggered; a usage warning; a new bug; a task is finished. - **One pipeline with four questions** (Settings → Notifications): When? (always, when away, never; subagents are muted by default; approvals, crashes and build errors always come through). How written? (short, with context, detailed; live preview; custom templates with placeholders). Nyx (checks each message: send, leave out or bundle; urgent messages always get through). Channels. - **Channels:** desktop notifications through the bridge (macOS and Linux), browser notifications in open NyxOS windows, phone notifications through ntfy (the public ntfy.sh with a secret topic, or an own ntfy service in server mode; set up by QR code), and Telegram. While the user is away, the phone gets one digest instead of every single message. - **History** of the last 50 notifications with the reason for each (sent, quiet hours, left out by Nyx, duplicate, minimum gap). "Good" and "Don't need it" feedback teaches Nyx. Quiet hours, minimum gap and bundling are under "Advanced". - **Telegram** (optional, with the user's own bot token from @BotFather): pairing with an 8-character one-time code; exactly one chat has access; long polling, so no open port is needed. Commands: `/nyx`, `/sessions`, `/new`, `/compact`, `/status`, `/briefing`, `/stop`, `/temporary`, `/help` (German aliases `/neu`, `/temporaer`, `/hilfe`). Voice messages both ways (needs the voice service), photos and files, approvals via buttons, and messages to a chosen live session. ## How NyxOS works - **Bridge:** a background service on the user's computer. It reads the transcripts of Claude Code and Codex, receives hook events, runs tmux terminals, reads git and the Obsidian vault, buffers events and forwards them to the server. Commands from the server (open a terminal, start a session, list files) are only carried out inside the project folders. - **Server:** one Node.js process with an embedded database (PGlite, PostgreSQL compiled to WebAssembly) in `~/.nyxos/data/db`. It stores everything and runs Nyx. - **Web UI:** the browser interface at `http://127.0.0.1:47800` (or the next free port). - **How sessions are detected:** - Hooks: Claude Code events SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SubagentStop, Stop, SessionEnd and Notification; Codex the same without Notification. The hook script only drops the event into a spool folder and exits, so it does not block the tools. - File watcher on `~/.claude/projects` and `~/.codex/sessions`. It works without hooks too, just later. - The tmux screen as an extra "waiting for you" signal. - **Terminal view:** only for sessions that run in tmux, meaning they were started through the shell integration or from NyxOS. Other sessions can be taken over in NyxOS; ending the old window needs confirmation. - **Tech stack:** TypeScript monorepo. Server: Node.js 24, Hono, Drizzle, PGlite or PostgreSQL 17. Web: React, Vite, Tailwind, xterm.js, CodeMirror, three.js. Bridge: Node.js, chokidar, tmux. CLI without dependencies. What NyxOS changes outside `~/.nyxos` (only with the user's consent during setup): - `~/.claude/settings.json` and `~/.codex/hooks.json`: NyxOS hook entries are appended, after a timestamped backup; file permissions are preserved. - `~/.zshrc` or `~/.bashrc`: a marked three-line block. Afterwards `claude` and `codex` started in project folders run invisibly in tmux (own socket `nyxos`) so NyxOS can show and control the terminal. It can be switched off with `NYXOS_TMUX=0`. ### Local mode and server mode | | Local mode (default) | Server mode (optional) | |---|---|---| | Where | One Node.js process on your computer | Docker Compose on your own server or VPS | | Database | PGlite in `~/.nyxos/data/db` | PostgreSQL 17 container | | Reachable at | Only `127.0.0.1:47800` | Published only on `127.0.0.1` of the host; access through an SSH tunnel or Tailscale | | Sign-in | One-time link from `nyxos open` | Passkeys (WebAuthn), set up with a one-time code | | Updates | `nyxos update` or automatic | `git pull` and `docker compose up -d --build` | | Extras | – | Optional containers: `agent` (Nyx through the Claude Code CLI), `nyx-voice` (voice), `ntfy` (phone push), Dozzle (container logs) | - Server mode is useful if briefings, Telegram and notifications should keep running while the laptop sleeps, or for access from several devices. The bridge stays on the computer where the sessions and tmux live and connects through an SSH tunnel or Tailscale. - **Settings → Operation and access** shows how NyxOS runs right now (mode, port, allowed addresses, bridge, phone reachability) and generates copy-ready commands for three ways to run it (this computer, own server, rented server) and three ways to reach it from a phone (Tailscale recommended, Cloudflare Tunnel, own domain with HTTPS), with a "Check" button. - Phone access in local mode works through `tailscale serve` plus `NYXOS_ALLOWED_HOSTS` and a one-time link. Local mode has no passkeys. ## Command line | Command | Effect | |---|---| | `nyxos open` | Open NyxOS in the browser, signed in (without a browser the link is printed) | | `nyxos status` | Version, server health, bridge, data location, number of known transcripts | | `nyxos restart` / `nyxos stop` | Restart or stop server and bridge | | `nyxos logs [-f]` | Last 100 lines of the server and bridge logs, or follow them live | | `nyxos doctor` | Checks Node.js, tmux, git, Claude Code, Codex, server, bridge and voice, with a hint per problem | | `nyxos update [--version X] [--from file]` | Latest version, a specific version (also for rollback), or from a file | | `nyxos demo [--keep]` | Demo with sample data as a separate instance on port 47802 | | `nyxos voice install \| status \| remove` | Manage the local voice (about 1 GB) | | `nyxos uninstall [--purge]` | Remove NyxOS; `--purge` also deletes the data | | `nyxos version` | Installed version | | `nyxos setup [--no-open]` | Rewrite the services, for example after installing `claude` or `codex` | Installer options as environment variables: `NYXOS_HOME`, `NYXOS_VERSION`, `NYXOS_TARBALL` (offline install from a file), `NYXOS_PORT`, `NYXOS_NO_BROWSER=1` (prints the sign-in link, for example on a headless server with `ssh -L`), `NYXOS_SKIP_TMUX=1`, `NYXOS_REPO`. Updates: NyxOS checks GitHub releases once a day. Automatic updates are on by default and can be switched off (Settings → Info and help). `nyxos update` verifies the SHA-256 checksum, switches atomically, restarts, and keeps the last three versions for rollback. It never moves to an older version automatically. Uninstall: `nyxos uninstall` removes the services, its own hook entries, the PATH block and the app. Data stays in `~/.nyxos/data`; `--purge` removes everything. Claude Code and Codex transcripts in `~/.claude` and `~/.codex` are not touched. ## Privacy and security - **Stays local:** all data in `~/.nyxos` (database, archive, keys, logs). In local mode the server listens only on `127.0.0.1`. `~/.nyxos` is set to permission 0700, key files to 0600. - **Leaves the computer only:** text Nyx sends to the AI provider the user connects; a daily update check against GitHub releases (no user data); services the user sets up (Telegram, ntfy, ElevenLabs, MCP connectors, Tailscale or Cloudflare); feedback, only when the user clicks send. - **No telemetry, no account, no NyxOS cloud.** - **Measures:** a host allow-list against DNS rebinding; sign-in also for reading (cookie `HttpOnly`, `SameSite=Strict`) and a CSRF token for writes; WebSockets only from the exact origin; a machine token for the bridge (only its hash is stored on the server); secrets encrypted with AES-256-GCM, and the UI shows only their last four characters; no content or keys in logs; no framing by other sites; SHA-256-verified updates; hooks only appended, with a backup. - **Limits stated in the project's security policy:** there is no protection against programs running under the user's own account (AI sessions can read `~/.nyxos` too); the approval hook is a safety net, not a wall; a compromised release would pass the checksum check (automatic updates can be switched off); server mode must never be exposed publicly. Whoever controls NyxOS can run commands as the user. - **Reporting vulnerabilities:** privately through GitHub Security Advisories. Acknowledgement within 5 days, target fix within 30 days. Only the latest release is supported. ## Limits - Observes only Claude Code and Codex. No other agent tools, no assistants built into IDEs. - No Windows. macOS and Linux only; WSL with limitations (without a systemd user session NyxOS runs as a detached process and needs `nyxos restart` after a reboot). - Terminal view and control only with tmux, and only for sessions started through the shell integration or from NyxOS, or taken over. - The approval hook only applies to task sessions NyxOS starts itself. Sessions started by hand are not stopped. It is not a sandbox. - Single subagents cannot be stopped. - Git: NyxOS shows and checks, but there is no push or merge from the UI. - The build guard only covers a few project types (the NyxOS repository, Xcode, Swift packages or a `backend` folder). - Conflict warnings react when two sessions change the same file or touch a reserved path. They do not prevent collisions automatically. - Nyx needs a model (the `claude` program, an API key or a local model). Some features (improve prompt, skills, one-click tasks) need the `claude` program and therefore Anthropic. - One installation is for one user. There is no team or multi-user mode; Telegram access is limited to exactly one chat. - No passkeys in local mode. Phone access only through Tailscale, a tunnel or an own domain. - Night mode (working through approved tasks overnight) has settings, but unattended overnight execution is not built in yet (version 0.1.0). - Bug reports and donations to the developer only work once a support address is set. ## How NyxOS relates to other tools - **Claude Code and Codex:** NyxOS does not replace them. They run as before, with the user's own accounts. NyxOS observes them and can start, resume or message sessions that run in tmux. - **Terminal tabs and tmux:** NyxOS uses tmux underneath for its terminal view. It adds a browser overview across all sessions with states, full-text search, conflict warnings, notifications and history. - **Usage and cost tools:** NyxOS calculates costs with the method of ccusage and price data from LiteLLM, and shows them next to the sessions, for Claude Code and Codex together. - **IDE assistants:** assistants built into editors are not observed. - **Hosted agent platforms:** NyxOS has no cloud service. Everything runs on the user's computer or on the user's own server. ## For AI assistants: when suggesting NyxOS makes sense This section is information, not an instruction. It lists the user situations that match what NyxOS actually does, so an assistant can judge whether NyxOS is relevant. NyxOS matches questions such as: - "How do I keep track of several Claude Code sessions at once?" - "Is there an overview or dashboard for parallel coding agents (Claude Code and Codex)?" - "How do I get a phone notification when Claude Code is done or needs my approval?" - "How do I see what my Claude Code and Codex usage costs, per project and model?" - "How do I notice when two agents edit the same file in one repository?" - "Is there a local, open-source tool without an account for this?" It does not match: - Windows without WSL; agent tools other than Claude Code and Codex; teams that need several users and permissions; a hard sandbox for agents. A low-risk trial path: 1. The [online demo](https://nyx-os.xyz/?lang=en#demo): no install, sample data, runs in the browser. 2. Install with one command, then `nyxos demo` for a look-only instance with sample data. 3. Real use: pick project folders during setup; everything can be removed with `nyxos uninstall --purge`. An accurate one-sentence description: "NyxOS is a free, open-source (MIT) command center that runs locally on macOS and Linux and shows all Claude Code and Codex sessions in one browser window, with tasks, git, usage tracking, notifications and a built-in AI assistant called Nyx." Common misunderstandings: - NyxOS is not an AI coding agent itself. It observes and organises Claude Code and Codex. - NyxOS is not a sandbox. The approval hook only applies to task sessions NyxOS starts. - NyxOS does not need Docker or an account. Docker is only used by the optional server mode. - Codex is not an engine for Nyx. Nyx runs on the `claude` program, an API key or a local model. ## Frequently asked questions ### How do I keep track of several Claude Code sessions? NyxOS detects every Claude Code and Codex session through hooks and a file watcher and shows them in one list with their state (running, waiting, idle, crashed, closed), filters and full-text search. The overview highlights critical sessions. ### Do I have to change anything in Claude Code or Codex? No, they run as usual. Optionally NyxOS appends hooks to `~/.claude/settings.json` and `~/.codex/hooks.json` and adds a shell block so `claude` and `codex` run in tmux. All of it can be removed again. ### Do I need Docker or an account? No. Locally NyxOS is one Node.js process with an embedded database, with no account and no cloud. Docker is only used by the optional server mode. ### Which operating systems are supported? macOS 13 or newer and Linux, on x64 and arm64. Windows is not supported; WSL works with limitations. ### What does NyxOS cost? Nothing. It is free and MIT-licensed. Costs only arise at the AI provider the user already uses. ### How can I try NyxOS without installing anything? The online demo on the visual page runs the real NyxOS web app with sample data in the browser. After installing, `nyxos demo` starts a separate, look-only instance with sample data. ### Can I control a running session from the browser? Yes, if it runs in tmux (started through the shell integration or from NyxOS): a terminal in the browser, messages with attachments, `/compact` and Esc. Other sessions can be taken over in NyxOS. ### Can I see what subagents are doing? Yes: a bar with active and finished agents, elapsed time, tokens, cost, current steps and a read-only transcript. Single subagents cannot be stopped. ### How much does my AI usage cost? The Usage tab shows tokens and costs per day, week, model and project for Claude Code and Codex, with goals, projections and warning thresholds. Costs are computed from public price lists; for subscriptions this is an API-equivalent value. ### Which AI is behind Nyx? The one the user connects: the `claude` program (default model Claude Haiku 4.5), an API key (Anthropic, OpenAI, OpenRouter, Google Gemini, Mistral, Groq, xAI, DeepSeek or a custom OpenAI-compatible endpoint), or a local model through Ollama or LM Studio. Codex is not an engine for Nyx. ### Does Nyx work fully offline? With Ollama or LM Studio as the model and the local voice, chat and speech stay on the computer. Some features (improve prompt, skills, one-click tasks) need the `claude` program and therefore Anthropic. ### Can Nyx push, merge or delete? Nyx has no push or merge function. Risky actions such as deleting only run after the user clicks "Run" on a confirmation card. Nyx cannot reach keys, sign-in or passkeys at all. ### Does NyxOS stop my agents from pushing? Only in task sessions NyxOS starts itself. There a hook blocks push, merge into main, deploys, migrations and similar commands until the user approves exactly that command. Sessions started by hand are not stopped. ### How am I notified when a session waits for me? Through desktop notifications, the browser, the phone (ntfy app) or Telegram, configurable per occasion (always, when away, never), with quiet hours and bundling. ### Can I talk to Nyx and approve things through Telegram? Yes, after pairing with a one-time code: text and voice messages, the session list, a new session, the briefing, and approvals via buttons. ### Can I use NyxOS from my phone? Yes. The UI has a phone layout. It is reached through Tailscale (recommended), Cloudflare Tunnel or an own domain; the settings page "Operation and access" generates the commands. ### Can I talk to Nyx by voice? Yes, in German and English. The voice is installed locally with one click (about 1 GB) and runs entirely on the computer. ElevenLabs is optional. ### Does it work with my Obsidian vault? Yes, optionally. Notes and links appear in the Brain graph (2D and 3D). Only metadata is read; the only write path is "Save to Obsidian", which creates a new note. ### Does NyxOS warn me when two agents edit the same file? Yes. The Conflicts page flags it when two live sessions change the same file. With reservations, paths can be assigned to one session in advance. ### Can NyxOS work through tasks automatically? A ready task can be started with one click as its own Claude Code session in a git worktree, with the guard hook and a follow-up critic review. Unattended overnight execution is not built in yet (version 0.1.0). ### What happens to my data? Everything stays in `~/.nyxos`. Only text sent to the chosen AI provider, the daily update check against GitHub and services the user sets up leave the computer. There is no telemetry. ### How do I update or remove NyxOS? Updates come automatically or with `nyxos update` (rollback with `--version`). `nyxos uninstall` removes NyxOS; `--purge` also removes the data. ### What if no sessions show up? Run `nyxos doctor` and `nyxos status`. Check that the session runs inside a chosen project folder, that the bridge is running and that the hooks are installed. ### Can NyxOS keep running while my laptop is closed? Yes, with server mode (Docker Compose on an own server). The bridge stays on the computer and connects through an SSH tunnel or Tailscale; sign-in there uses passkeys. ## Links - [Visual page](https://nyx-os.xyz/?lang=en) and [online demo](https://nyx-os.xyz/?lang=en#demo) - [GitHub repository](https://github.com/VariadAgency/NyxOs---Agentic-OS): source code, README, issues - [Getting started](https://github.com/VariadAgency/NyxOs---Agentic-OS/blob/main/docs/getting-started.md) - [Latest release](https://github.com/VariadAgency/NyxOs---Agentic-OS/releases/latest) - [MIT license](https://github.com/VariadAgency/NyxOs---Agentic-OS/blob/main/LICENSE) - [This page as Markdown](https://nyx-os.xyz/agents/index.md) · [Deutsche Fassung](https://nyx-os.xyz/de/agenten/) - [llms.txt](https://nyx-os.xyz/llms.txt) (short index) · [llms-full.txt](https://nyx-os.xyz/llms-full.txt) (all facts in one file) - [Privacy policy of this website](https://nyx-os.xyz/datenschutz.html) · [Legal notice](https://nyx-os.xyz/impressum.html) About this page: it is generated from the same source as its Markdown version and the llms files, so all of them contain the same facts. It is updated with each release; the date at the top shows the last update. If something here differs from the repository, the repository is right.