Nosis is an open-source, lightweight personal agent application. It provides local workspace operations, human approval, session persistence, context management, long-term memory, plans, subagents, scheduled tasks, and Skill / Plugin / MCP extensibility — with both a TUI and a GUI.
TUI ────────────┐
├── Bridge ── agent_runtime ── agent_core
GUI ── FastAPI ─┘
agent_coreprovides frontend-agnostic agent mechanisms.agent_runtimereads application configuration and assembles the Core into a runnable instance.- Bridge runs as a standalone process and is the only channel through which a frontend drives the Runtime.
- The TUI and GUI hosts share execution state and interaction semantics through the Bridge protocol; the Bridge subprocess channel uses newline-delimited JSON.
- Controlled local execution: A session supports three permission presets —
Ask for approval,Workspace Access, andFull Access. Shell enters the workspace sandbox or the host environment according to scope, while file tools are always confined to the current workspace. - Desktop automation: The main agent can observe and operate the visible desktop through
computer_screenshotandcomputer_action, covering screenshots, clicks, drags, scrolling, key presses, and text input. Both tools are on by default and visible only to the main agent, and each call is confirmed according to the current permission preset. - Web research:
web_fetchreads public pages;web_search, when enabled, queries DuckDuckGo by default and can switch to Exa. - A complete agent loop: streaming responses, tool batches, context compaction, steer, cancel, plans, and background jobs.
- Resumable sessions: conversation and execution events are written to an append-only JSONL journal, and the TUI and GUI can read the same kind of session.
- Memory and scheduled tasks: global and workspace-scoped long-term memory, plus one-shot, interval, and cron tasks.
- Models and media: OpenAI-compatible endpoints use the native OpenAI SDK; other routes and image generation use LiteLLM. Providers can be routed independently for the main agent, vision, image generation, auxiliary model calls, and each subagent role.
- Extension system: standalone skills, skills / agents / MCP components provided by plugins, and standalone MCP servers.
- Two frontends: the TUI suits terminal workflows; the GUI offers multi-session management, attachments, a file tree, settings, memory, and scheduled tasks.
Requirements: Python >= 3.11, Node.js >= 22, and uv.
git clone https://github.com/EvannZhongg/Nosis.git
cd Nosis
npm install
npm run build
uv tool install --editable ".[gui]"If you create the project environment with uv sync, install the GUI extra as well, otherwise Uvicorn cannot serve the session WebSocket:
uv sync --extra guiStart the TUI once in the current directory:
nosisThe first launch initializes ~/.nosis/. After quitting the TUI, create ~/.nosis/.env and fill in the environment variables required by the default provider, for example:
OPENAI_KEY=your-api-keyThen restart the TUI:
nosisOr start the GUI:
nosis-guiThe GUI listens on http://127.0.0.1:8737 by default.
| Document | Scope |
|---|---|
agent_core |
Agent loop, context, session, tools, execution, permissions, memory, plans, jobs, scheduler, providers, skills, and MCP mechanisms |
agent_runtime |
Configuration, prompts, plugin discovery, runtime assembly, execution plane, session binding, and turn entry |
interfaces/bridge |
The standalone Bridge process, protocol routing, event translation, and frontend interaction forwarding |
interfaces/protocol |
The TypeScript protocol types and connection-state conventions shared by the TUI and GUI |
interfaces/tui |
The Ink terminal interface, commands, input state, and Bridge subprocess attachment |
interfaces/gui |
The FastAPI service, React interface, multi-session connections, HTTP / WebSocket API, and media access |
agent_runtime creates the configuration directory on first launch and is responsible for reading and updating the application configuration inside it:
| Path | Contents |
|---|---|
~/.nosis/provider_config.json |
Providers, models, and role routing, including the optional fast_model |
~/.nosis/agent_config.json |
Tools, context, memory, skill paths, subagents, MCP, workspace instructions, and scratch workspace settings |
~/.nosis/.env |
The secrets and environment variables referenced by the configuration |
~/.nosis/prompts/ |
Main agent, subagent, compaction, and memory prompts |
~/.nosis/skills/ |
Standalone skills |
~/.nosis/plugins/ |
Plugin capability packages |
~/.nosis/AGENTS.md |
User-level global workspace instruction |
~/.nosis/MEMORY.md |
Global long-term memory |
~/.nosis/sessions/ |
Session journals, workspace memory, artifacts, subagent records, and per-session auxiliary usage logs |
~/.nosis/schedule.jsonl |
Scheduled tasks and run records |
<workspace>/.nosis/attachments/ |
Uploaded attachments and agent-generated images |
The default configuration and built-in resources live in agent_runtime/defaults/. See agent_runtime/README.md for how assembly works.
Python tests use a mock provider and need no real API key:
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[gui]"
python -m unittest discover -s tests -vOn Windows, activate the environment with .venv\Scripts\Activate.ps1.
The GUI extra includes FastAPI, Uvicorn, the WebSocket backend, and multipart support; Windows, macOS, and Linux use the same installation.
Frontend build, type checking, and tests:
npm run build
npm run typecheck
npm testThe Linux sandbox integration tests require a working bubblewrap and user namespaces; when the runtime conditions are not met, the tests explicitly skip.
On Windows the shell tool uses PowerShell 7, so PowerShell 7 has to be installed separately.