{"id":51169700,"url":"https://github.com/arthurdev44/numen","last_synced_at":"2026-06-26T23:04:04.533Z","repository":{"id":365336411,"uuid":"1270170786","full_name":"ArthurDEV44/numen","owner":"ArthurDEV44","description":"Terminal AI coding agent in native Rust — Claude Code quality, open to all frontier models (Anthropic, OpenAI, Gemini…). Headless event-only core shared with Paneflow, Ratatui frontend.","archived":false,"fork":false,"pushed_at":"2026-06-16T22:15:08.000Z","size":403,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T00:12:15.038Z","etag":null,"topics":["agentic","ai-agent","claude-code","cli","coding-agent","llm","ratatui","rust","tui"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ArthurDEV44.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-15T13:02:55.000Z","updated_at":"2026-06-16T22:15:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ArthurDEV44/numen","commit_stats":null,"previous_names":["arthurdev44/numen"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ArthurDEV44/numen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurDEV44%2Fnumen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurDEV44%2Fnumen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurDEV44%2Fnumen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurDEV44%2Fnumen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArthurDEV44","download_url":"https://codeload.github.com/ArthurDEV44/numen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurDEV44%2Fnumen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34835782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai-agent","claude-code","cli","coding-agent","llm","ratatui","rust","tui"],"created_at":"2026-06-26T23:04:03.864Z","updated_at":"2026-06-26T23:04:04.512Z","avatar_url":"https://github.com/ArthurDEV44.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Numen\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Status\" src=\"https://img.shields.io/badge/status-early%20development-orange\"\u003e\n  \u003cimg alt=\"Rust\" src=\"https://img.shields.io/badge/Rust-1.95-orange?logo=rust\"\u003e\n  \u003cimg alt=\"Platform\" src=\"https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20next-informational\"\u003e\n  \u003cimg alt=\"Provider\" src=\"https://img.shields.io/badge/provider-ChatGPT%20subscription-black?logo=openai\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-GPL--3.0--or--later-blue\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**A native, model-agnostic AI coding agent that lives in your terminal.** `numen` opens straight in your shell, streams a model, runs real tools (read, grep, edit, bash), and loops until the work is done, all from a single Rust binary with no Node runtime underneath.\n\nNumen is built around a **headless core** (`agent-core`) that emits only structured events, never ANSI. The terminal UI is just one client. That same core is meant to be embedded in-process by [Paneflow](https://paneflow.dev) (Zed's GPUI) for GPU-accelerated diffs and plan trees later, without forking any agent logic. The provider layer is multi-provider by design (a clean `Provider` trait + an Anthropic-shaped canonical format), so new model backends drop in as isolated adapters.\n\n\u003e *Numen* (Latin): the animating will, the guiding presence. It keeps the soul of *daimon*, a guide-spirit for your codebase.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#status\"\u003eStatus\u003c/a\u003e ·\n  \u003ca href=\"#quickstart\"\u003eQuickstart\u003c/a\u003e ·\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e ·\n  \u003ca href=\"#how-it-works\"\u003eHow it works\u003c/a\u003e ·\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e ·\n  \u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e ·\n  \u003ca href=\"#faq\"\u003eFAQ\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/images/welcome.png\" alt=\"Numen's welcome screen: a monochrome terminal card with a braille Dyson-sphere logo, running on a ChatGPT subscription (codex, gpt-5.5)\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eThe welcome screen: a native terminal agent on your ChatGPT subscription (gpt-5.5 via codex), monochrome, no window.\u003c/sub\u003e\n\u003c/p\u003e\n\n```console\n$ numen\n  numen · gpt-5.5 · ~/dev/myproject\n\n› refactor the auth module to drop unwrap() in prod paths\n\n  ⠋ read   crates/auth/src/token.rs\n  ⠙ edit   crates/auth/src/token.rs   (3 hunks)\n  ✓ bash   cargo clippy --no-deps  ·  0 warnings\n\n  Replaced 4 unwrap() with ? / ok_or(...). Diff above.\n\n# headless, scriptable, no TUI\n$ numen -p \"summarize the changes in the last commit\"\n```\n\n## Status\n\n**Early, single-provider, Linux-first. No packaged releases yet, you build from source.** This is an honest snapshot, not a roadmap fantasy:\n\n- **It runs today.** The agentic loop, the tool suite, the sandbox, JSONL sessions with resume, MCP, and the monochrome TUI all work.\n- **One model channel ships so far: your ChatGPT subscription.** GPT / Codex models served through the Codex backend (Responses API, SSE, stateless). The provider layer is written multi-provider from day one, but this is the only adapter wired up. Anthropic, OpenAI BYOK, Gemini, and others are architecture-ready, not yet built. See [Roadmap](#roadmap).\n- **Linux is the supported platform.** The filesystem sandbox uses Landlock (Linux kernel) and credentials use the Secret Service keyring. macOS Seatbelt and broader support come later; off-Linux, FS confinement degrades explicitly.\n- **The subscription auth is unofficial and revocable.** It reuses the open-source Codex CLI OAuth client, which is ToS-grey and could be cut off at any time (it happened to Anthropic Pro/Max for third-party tools in 2026). Treat it as a convenience, not a foundation. See [Authentication](#authentication).\n\n## Quickstart\n\nYou need a Rust toolchain (1.95+) and a Linux desktop session with a Secret Service keyring (GNOME Keyring or KWallet) for credential storage.\n\n```bash\n# 1. Build from source\ngit clone https://github.com/ArthurDEV44/numen.git\ncd numen\ncargo build --release          # produces target/release/numen\n\n# 2. Authenticate with your ChatGPT subscription (OAuth, opens a browser)\ncargo run -p agent-auth --example login\n\n# 3. Run it in any project directory\ncd ~/dev/myproject\n/path/to/numen/target/release/numen\n```\n\nDrop `target/release/numen` on your `PATH` (or `cargo install --path crates/agent-cli`) to call `numen` from anywhere.\n\n## Where it fits\n\nNumen overlaps with every terminal coding agent, but the design center is specific: **a native, model-agnostic agent whose core is built to be embedded in a GPU terminal workspace.**\n\n| Tool | Strength | Numen's angle |\n|---|---|---|\n| Claude Code | Polished Anthropic-native agent, large ecosystem | Model-agnostic core by design; one native Rust binary, no Node runtime |\n| Codex CLI | OpenAI-native, strong sandboxing | Reuses the ChatGPT-subscription channel, but ships a headless core meant to embed in Paneflow |\n| aider / opencode | Mature multi-model OSS agents | Rust-native, kernel-level FS sandbox (Landlock), shared core with a GPU terminal workspace |\n| Paneflow | Runs CLI agents in parallel GPU panes | Numen is the agent; Paneflow is the surface. The plan is to embed `agent-core` in-process, no IPC |\n\nThe honest caveat: most rows describe a *direction*. Today Numen ships one provider and one frontend. The bet is in the architecture (headless core + provider trait), not in a checklist.\n\n## Features\n\nShipped today:\n\n- **Agentic loop**: stream → tool → loop, driven by a compiler-checked transition state machine. The model calls tools, sees results, and continues until it ends the turn.\n- **Built-in tool suite**: `read`, `glob`, `grep`, `write`, `edit`, `bash`. Concurrency-safe reads run in parallel; mutations run serially.\n- **Fail-closed permissions + taint**: every tool is dangerous until proven otherwise. Tool output is untrusted by default (OWASP LLM01); a destructive or network action in a turn that just read untrusted content is forced to ask, regardless of mode.\n- **Execution sandbox**: Landlock confines all writes to the workspace (the agent *and* its `bash` subprocesses); a fail-closed local proxy gates outbound network from tool subprocesses via `--allow \u003chost\u003e`.\n- **Persistent sessions**: one append-only JSONL file per conversation under `.numen/sessions/`, with `/resume` to reopen a past session and a workspace-wide prompt history.\n- **`/goal` completion loop**: set a session objective and Numen re-runs the agentic loop until it emits a done marker (capped at 25 iterations), persisted in a `.numen/goal` sidecar so it survives restarts.\n- **MCP (stdio)**: connect to Model Context Protocol servers from `.mcp.json` or your existing `~/.claude.json`, managed from the `/mcp` submenu.\n- **Markdown rendering**: assistant replies are rendered to styled spans (CommonMark + GFM).\n- **Monochrome Ratatui UI**: clean, modern, Rauch/Vercel-flavored, with a braille Dyson-sphere logo and a welcome screen, not a double-bordered retro TUI.\n- **Headless mode**: `numen -p \"...\"` runs without the TUI, so the core is scriptable and testable without a terminal or a live API.\n- **ChatGPT subscription auth**: OAuth PKCE, refresh-token rotation, credentials in the OS keyring (never in plaintext).\n\nArchitecture-ready, not yet built:\n\n- Additional provider adapters (Anthropic, OpenAI BYOK, Gemini) behind the same `Provider` trait\n- Paneflow in-process embedding with GPU diffs, plan trees, and hunk review\n- Vector memory (`sqlite-vec`), sub-agents, prompt-caching strategy, VCR provider tests\n\n## How it works\n\nNumen is a Cargo workspace. The crates are named `agent-*` internally; the published binary and command are `numen` (see [`docs/DECISIONS.md`](docs/DECISIONS.md), ADR-8).\n\n```\n                         ┌──────────────────────────────┐\n                         │          agent-core           │\n                         │  loop + state machine +       │\n                         │  canonical types (headless)   │\n                         │  emits: Stream\u003cAgentEvent\u003e    │\n                         └──────────────┬───────────────┘\n                                        │  structured events (never ANSI)\n                 ┌──────────────────────┼──────────────────────┐\n                 ▼                      ▼                      ▼\n        ┌─────────────────┐    ┌─────────────────┐    ┌──────────────────┐\n        │   agent-tui     │    │   mode -p       │    │ Paneflow (GPUI)  │\n        │ Ratatui client  │    │ headless print  │    │ embed in-process │\n        │ (terminal)      │    │ (text / JSON)   │    │ GPU render (next)│\n        └─────────────────┘    └─────────────────┘    └──────────────────┘\n```\n\nThe founding invariant: **`agent-core` depends on neither the TUI nor the provider layer** (only on `agent-tokenizer`, which is also headless). I/O is injected through traits, so the loop is testable without network, terminal, or a real model. The provider layer normalizes heterogeneous wire formats into one Anthropic-shaped canonical format, with divergences localized per adapter.\n\n| Crate | Role |\n|---|---|\n| `agent-core` | Agent loop, transition state machine, canonical message/transcript types (headless) |\n| `agent-provider` | `Provider` trait + adapters (reqwest + SSE), canonical `StreamEvent`, error taxonomy |\n| `agent-tools` | Tool registry, fail-closed trait, concurrent/serial dispatch, permissions, taint |\n| `agent-mcp` | `rmcp`-based MCP client (stdio), config loading, server registry |\n| `agent-tui` | Ratatui + crossterm frontend, decoupled from the core via channels |\n| `agent-session` | Append-only JSONL persistence, resume, compaction boundaries |\n| `agent-sandbox` | Landlock FS confinement + local network allow-list proxy |\n| `agent-auth` | Credential storage (keyring), OAuth PKCE, token refresh |\n| `agent-tokenizer` | Local token counting (fallback when a provider omits stream usage) |\n| `agent-cli` | The `numen` binary, the only crate that wires everything together |\n\nFull detail in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).\n\n## Authentication\n\nNumen authenticates with your **ChatGPT subscription** (Plus / Pro), not a metered API key. The flow:\n\n```bash\ncargo run -p agent-auth --example login\n```\n\nThis runs OAuth PKCE against `auth.openai.com`, then talks to the ChatGPT backend's Responses API (`chatgpt.com/backend-api/codex/responses`) in stateless SSE mode, so the full transcript is sent each turn and compaction / resume / replay stay intact. Tokens are stored in the OS keyring and refreshed automatically.\n\n**Read this before you rely on it.** The login reuses the OAuth client of the open-source Codex CLI, which effectively impersonates Codex. That is ToS-grey and **revocable**: OpenAI could disable this client at any time, exactly as Anthropic blocked third-party tools from using Pro/Max subscriptions in 2026. Numen treats the subscription as a disposable convenience layer, not a foundation. The day it breaks, adding a BYOK adapter (Chat Completions, Anthropic, ...) is an isolated module, not a rewrite. The model-agnostic architecture is the insurance policy. See [`docs/DECISIONS.md`](docs/DECISIONS.md) (ADR-10, ADR-11) and [`docs/openai-subscription-auth.md`](docs/openai-subscription-auth.md).\n\n## Build from source\n\n### Rust toolchain\n\nNumen uses Rust **1.95+** (edition 2024). Install via [rustup](https://rustup.rs/):\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n```\n\n### Linux system dependencies\n\nCredential storage uses the Secret Service API, so you need a keyring daemon (GNOME Keyring or KWallet) and its dev headers. TLS uses rustls, so OpenSSL is not required.\n\n**Fedora:**\n```bash\nsudo dnf install gcc pkgconf-pkg-config libsecret-devel\n```\n\n**Debian / Ubuntu:**\n```bash\nsudo apt install build-essential pkg-config libsecret-1-dev\n```\n\n### Build and test\n\n```bash\ncargo build --release          # binary at target/release/numen\ncargo test --workspace         # headless core is fully testable without a live API\n```\n\nThe filesystem sandbox needs a Linux kernel with Landlock (5.13+, ABI improvements through 6.x). Without it, Numen warns and runs unconfined rather than failing closed.\n\n## Usage\n\n```bash\nnumen                          # interactive TUI in the current directory\nnumen -p \"\u003cprompt\u003e\"            # headless one-shot, prints the answer and exits\nnumen \"\u003cprompt\u003e\"               # bare prompt is treated as -p\n```\n\n### Flags\n\n| Flag | Effect |\n|------|--------|\n| `--model \u003cslug\u003e` | Pick the model (default `gpt-5.5`). Also switchable in-session via `/models`. |\n| `--allow \u003chost\u003e` | Add a host to the network allow-list for tool subprocesses (repeatable). |\n| `--yes`, `-y` | Auto-approve tool actions (headless / trusted automation). |\n| `--no-sandbox` | Disable Landlock FS confinement (writes are no longer confined to the workspace). |\n\n### Slash commands (interactive)\n\n| Command | Action |\n|---------|--------|\n| `/help` | List available commands |\n| `/models` | Switch the active model for this session |\n| `/goal` | Set an objective and work until it is reached |\n| `/skills` | Insert a skill from `~/.agents/skills` into the message |\n| `/providers` | Inspect / configure the auth provider |\n| `/mcp` | Manage MCP server connections |\n| `/resume` | Reopen a past conversation |\n| `/new`, `/clear` | Start fresh (clear the context) |\n| `/quit` | Exit |\n\n### Models\n\nThe Codex backend accepts a whitelist of versioned slugs it rotates. The generic `gpt-5` slug is rejected; use a versioned one:\n\n`gpt-5.5` (default) · `gpt-5.4` · `gpt-5.4-mini` · `gpt-5.3-codex-spark`\n\n## Files and configuration\n\nNumen reads and writes a few well-known paths:\n\n| Path | Purpose |\n|------|---------|\n| `\u003cworkspace\u003e/.numen/sessions/*.jsonl` | One append-only transcript per conversation; backs `/resume` |\n| `\u003cworkspace\u003e/.numen/goal` | Persistent `/goal` objective (survives restarts) |\n| `\u003cworkspace\u003e/.mcp.json` | Workspace MCP servers (highest priority) |\n| `~/.claude.json` | Reused `mcpServers` from Claude Code, merged underneath |\n| `~/.agents/skills/\u003cname\u003e/` | Skills surfaced by `/skills` (one directory per skill) |\n\nThese paths outside the workspace (skills, MCP config, keyring) are read **before** the Landlock sandbox is applied, since they would be unreachable afterward.\n\n## Sandbox and security\n\n- **Filesystem**: Landlock confines every write to the workspace, kernel-level, inherited by `bash` subprocesses (the FS sandbox is applied on the main thread before the Tokio runtime is built, so workers inherit it).\n- **Network**: a local CONNECT proxy with a fail-closed allow-list. Tool subprocesses get `HTTP(S)_PROXY` pointing at it (`--allow` opens specific hosts). The agent's own provider calls go direct.\n- **Prompt injection (OWASP LLM01)**: tool output is tainted as untrusted and the taint propagates; a destructive or network action following recent taint is forced to ask.\n- **Fail-closed tools**: a tool that declares nothing is treated as non-concurrent, mutating, and untrusted.\n- **Credentials**: OAuth tokens live in the OS keyring, never in plaintext on disk.\n\n## Roadmap\n\nThe MVP target was deliberately narrow: **make Numen excellent with one model channel (the ChatGPT subscription) and dogfood it daily**, rather than ship six empty provider columns. The multi-provider architecture is the invariant; adapters land incrementally.\n\n- **Now (shipped)**: agentic loop, tool suite + sandbox, sessions + resume, `/goal`, MCP stdio, monochrome TUI, ChatGPT subscription provider.\n- **Next**: more provider adapters behind the existing `Provider` trait, MCP tools wired into the model loop, Paneflow in-process embedding (GPU diffs, plan trees, hunk review).\n- **Later**: vector memory (`sqlite-vec`), sub-agents, macOS Seatbelt hardening, VCR provider tests in CI.\n\nPhases and the de-risking spikes live in [`docs/ROADMAP.md`](docs/ROADMAP.md).\n\n## Documentation\n\n| Document | Contents |\n|---|---|\n| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Crate workspace, agent loop, tool pipeline, compaction, sessions, sandbox |\n| [`docs/PROVIDERS.md`](docs/PROVIDERS.md) | Provider trait, canonical format, per-provider divergences, retry and caching |\n| [`docs/DECISIONS.md`](docs/DECISIONS.md) | Architecture decision records (language, frontend, naming, providers, risks) |\n| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Phases, de-risking spikes, sequencing |\n| [`docs/openai-subscription-auth.md`](docs/openai-subscription-auth.md) | ChatGPT subscription auth mechanics |\n\n## FAQ\n\n**Why Rust and not TypeScript like Claude Code?**\nThe whole point is sharing a core with Paneflow, which is GPUI (Rust). A Rust core can be embedded in-process with shared types and no IPC. A TS core hits an FFI wall. The accepted cost is slower solo dev velocity; the mitigation is a tight scope and decoupled, testable crates.\n\n**Why does it only work with a ChatGPT subscription today?**\nSequencing, not abandonment. The author orchestrates agents all day and wanted *his* model working perfectly first, then to add other providers over time. The `Provider` trait keeps the door open; the canonical format and retry/auth layers already exist.\n\n**Is this allowed? Will my account get banned?**\nThe subscription login reuses the open-source Codex CLI's OAuth client, which is unofficial and ToS-grey. It works for personal use and is revocable. If that risk is unacceptable to you, wait for the BYOK adapters.\n\n**Can I use my Anthropic Max subscription?**\nNo. Anthropic blocks third-party tools from authenticating with Pro/Max subscriptions. That is precisely why Numen is model-agnostic by design and does not depend on any single subscription channel.\n\n**Is this a Claude Code wrapper?**\nNo. It is an independent Rust implementation inspired by Claude Code's internal architecture (headless loop, transcript-before-response, compaction cascade, fail-closed tools), not a shell over it.\n\n**Is it ready for daily use?**\nIt is dogfooded daily by its author on Linux, but it is early: one provider, no releases, Linux-first, and a revocable auth channel. Build from source and expect rough edges.\n\n**Why GPL-3.0?**\nNumen is free and open source by design, and copyleft keeps it that way: improvements to the agent stay in the commons, and the shared core cannot be forked into a closed product.\n\n**How does it relate to Paneflow?**\nPaneflow runs CLI agents in parallel GPU panes; Numen is one such agent. The deeper plan is for Paneflow to embed `agent-core` in-process and render its events natively (GPU diffs, plan trees). That embedding is future work; the decoupling that makes it possible exists today.\n\n## License\n\n[GPL-3.0-or-later](LICENSE). Numen is free and open source by design, and copyleft keeps it that way: improvements stay in the commons.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurdev44%2Fnumen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farthurdev44%2Fnumen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurdev44%2Fnumen/lists"}