{"id":"f5d2fc4b-2962-46f4-b6d2-82e67bb979c1","slug":"nusashell","kind":"mcp","name":"NusaShell","summary":"NusaShell is a local, personal AI shell written in Go — single binary, embedded native-JS frontend, multi-conversation agent chat, provider adapters, MCP, skills, memory, and local docs.","owner":"jahrulnr","repoUrl":"https://github.com/jahrulnr/NusaShell","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-09T18:04:25.000Z","addedAt":"2026-10-21T06:35:02.884Z","logoUrl":"https://avatars.githubusercontent.com/u/73051140?u=834902aaade3c9c1a3cfafb44af31ac483726c22&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","communication"],"tags":["ai","ai-agent","go","pwa","electron"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T14:53:10.739Z","sample":false,"url":"https://conduits.dev/tools/nusashell","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# NusaShell\n\n[![CI](https://github.com/jahrulnr/NusaShell/actions/workflows/ci.yml/badge.svg)](https://github.com/jahrulnr/NusaShell/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Go 1.26+](https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go&logoColor=white)](go.mod)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](.github/pull_request_template.md)\n\nNusaShell is a local, personal AI shell written in Go. It delivers the\nNusaShell conversation experience in a single binary: an embedded native\nJavaScript frontend, multi-conversation agent chat, provider adapters, MCP,\nskills, memory, and documentation tools.\n\nThe interface follows the NusaShell Electron renderer closely, including the\nconversation rail, workspace picker, context counter, attachment affordance,\nstreaming tool timeline, and expandable reasoning and tool output.\n\n## What it includes\n\n- **Agent conversations** — streaming turns, stop/interrupt, automatic context\n  compaction, provider prompt caching, context usage, file attachments, and a\n  folder-backed workspace selected through the native picker.\n- **Readable execution timeline** — reasoning is rendered as Markdown, and\n  tool calls are collapsed by default. Expand a call only when needed; outputs\n  longer than ten lines scroll inside their own panel instead of stretching the\n  conversation.\n- **Providers** — Messages, Responses, and Chat API formats for Anthropic,\n  OpenAI-compatible services, DeepSeek, LM Studio, vLLM, and similar\n  endpoints. API keys are kept in a local SQLite credential store.\n- **MCP, skills, memory, and docs** — stdio MCP tools are available to the\n  agent as `mcp__<server>__<tool>`; reusable Markdown skills, durable memory,\n  and local documentation search round out the workspace.\n- **Local-first delivery** — Go serves the frontend assets embedded with\n  `embed.FS`. Production use needs no Node runtime, `node_modules`, or frontend\n  build step.\n- **Desktop pet (Linux)** — an optional SDL2 overlay (`nusashell-pets`) that\n  renders the alpha-shaped NusaShell mascot always-on-top and reacts to agent\n  activity over WebSocket. Built under `apps/pets` and installed as an\n  opt-in release component, currently Linux-only.\n\n## Quick start\n\nRequirements:\n\n- Go 1.26.5 or newer\n- Node.js 24 or newer for frontend tests and E2E checks\n- Nothing extra for workspace selection: the in-app folder browser walks the\n  server's directories from any device, including mobile browsers on the LAN.\n\n```bash\n# SSH (recommended for contributors with commit access)\ngit clone git@github.com:jahrulnr/NusaShell.git\n# or HTTPS\ngit clone https://github.com/jahrulnr/NusaShell.git\ncd NusaShell\n\n# Keep the local UI private to this machine.\nexport NUSASHELL_HOST=127.0.0.1\nmake run\n```\n\nOpen `http://127.0.0.1:10994`, configure a provider, then choose a folder from\nthe composer’s workspace button. The selected folder is the workspace for the\nactive conversation.\n\n### Release installer\n\nThe release installer installs the Go core first and then asks whether the\nlogin service (autostart), the optional Electron desktop wrapper, the\ndesktop pet (Linux only), and `NusaShell-mcp` plugins should be installed.\nRelease payloads cover Linux x64/ARM64, macOS x64/ARM64, and Windows\nx64/ARM64:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/jahrulnr/NusaShell/master/scripts/install.sh | bash\n```\n\nUse `--install-service`/`--no-service`,\n`--install-electron`/`--no-electron`,\n`--install-pets`/`--no-pets`, and\n`--install-mcp`/`--no-mcp` to choose explicitly. The desktop pet is currently\nLinux-only; the installer on macOS ignores pets options. On Linux, Electron\nand pets prompts are skipped when no desktop session (`DISPLAY` or\n`WAYLAND_DISPLAY`) is detected, which keeps proot/server installs clean;\nexplicit install flags still override that detection. Set\n`NUSASHELL_NON_INTERACTIVE=1` for unattended installs; optional components\ndefault to not installed. See [`docs/INSTALL.md`](docs/INSTALL.md) for\nWindows, layouts, version pinning, MCP details, and the\n`nusashell service` commands.\n\nWindows uses the equivalent PowerShell installer (pets is not offered there\nyet). It selects the x64 or ARM64 payload automatically and skips Electron\nplus shortcuts on Server Core/headless sessions unless `-InstallElectron` is\nexplicit:\n\n```powershell\nirm https://raw.githubusercontent.com/jahrulnr/NusaShell/master/scripts/install.ps1 | iex\n```\n\n### Electron desktop app\n\nThe cross-platform Electron app is a thin wrapper around the same Go server\nand native frontend. It does not duplicate the web UI or its interactions, and\nits release package never embeds the Go binary:\n\n```bash\nmake -C apps/electron dev           # build the local backend and launch Electron\nmake -C apps/electron test          # run wrapper tests without a GUI\nmake -C apps/electron ui-test       # launch Electron and test composer/workspace flows\nmake -C apps/electron package       # create an unpacked app directory\nmake -C apps/electron dist          # create a native installer for this OS\nmake -C apps/electron install-local # install the unpacked app into the user profile\nmake go-release                     # package the standalone Go core for this Unix platform\n```\n\nSee [`docs/electron.md`](docs/electron.md) for the runtime boundary,\ndevelopment overrides, packaging, and CI details. See\n[`docs/INSTALL.md`](docs/INSTALL.md) for release installers and versioning.\n\nTo install from this checkout (build Go, then optionally pets/Electron):\n\n```bash\nmake install              # interactive local build+install (scripts/install-local.*)\nnusashell                 # starts the server (default http://127.0.0.1:10994)\n```\n\nTo install published GitHub releases (same as curl / irm):\n\n```bash\nmake install-release      # scripts/install.sh / install.ps1\n```\n\nFor a flat checkout-only Go CLI copy without the versioned layout:\n\n```bash\nmake install-bin          # builds ./bin/nusashell → ~/.local/bin\n```\n\nSet `NUSASHELL_INSTALL_DIR` to change the `install-bin` destination. Optional\nlocal/release components use the flags/env documented in\n[`docs/INSTALL.md`](docs/INSTALL.md).\n\n## Development and verification\n\n```bash\nmake fmt                 # format Go sources\nmake fmt-check           # report unformatted Go sources\ngo test ./...            # ordinary Go test run\ngo test -race ./...      # race-enabled test run\ngo vet ./...             # static analysis\ngo build ./...           # compile every package\nmake check               # fmt-check + race test + vet + build + frontend tests\nmake verify-local        # full local gate + Windows/macOS compile checks\nmake -C apps/electron test    # Electron wrapper unit tests\nmake -C apps/electron ui-test # real Electron renderer interaction smoke test\nmake -C apps/electron dev     # run NusaShell in the Electron desktop shell\nmake installer-test      # installer/version/manifest contract tests\nmake go-release          # standalone Go core payload\nmake go-release-manifest # standalone Go release manifest\nmake go-version          # print the Go release version\nmake -C apps/electron version # print the Electron release version\nmake release-index-check # validate independent release pointers\n```\n\nThe local gate also runs the frontend test suite. Install its development\ndependency once with `npm ci`. To run the same gate automatically before every\npush, enable the repository hook once per clone:\n\n```bash\nmake hooks\n```\n\n`make verify-local` runs native tests (with `-race` when the local C compiler is\navailable), formatting, UI documentation drift checks, vet, builds, frontend\ntests, and compile-only checks for the Windows and macOS CI targets. A\ncross-compiled test binary cannot run on a different kernel, so runtime\nbehavior remains covered by the native runners in GitHub Actions.\n\n`make hooks` changes this clone’s repository-local `core.hooksPath`. If you\nalready use global Git hooks, preserve or chain them before enabling it.\n\nThe production frontend is plain browser JavaScript, but its browser-facing\nchecks use JSDOM:\n\n```bash\nnpm ci\nnode --test frontend/tests/*.test.mjs\n```\n\nThe E2E test starts the real Go server and exercises a representative flow\nthrough RPC, WebSocket events, application services, and local persistence.\n\n## Configuration\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `NUSASHELL_HOST` | `127.0.0.1` | HTTP listen host |\n| `NUSASHELL_PORT` | `10994` | HTTP listen port |\n| `NUSASHELL_DATA_DIR` | platform config directory plus `nusashell` | Local data directory |\n| `NUSASHELL_DEV` | unset | Serve `frontend/` directly from disk for development |\n\nUse `NUSASHELL_DEV=1` when iterating on the UI. The server keeps the same\nhandler contract in development and production; only the source of static\nassets changes.\n\n## Project layout\n\n| Path | Responsibility |\n| --- | --- |\n| `domain/` | Pure entities, value objects, and policies |\n| `application/` | Use cases, ports, agent runner, and event bus |\n| `contracts/` | Wire types, method roster, and JSON fixtures |\n| `infrastructure/` | Local stores, provider adapters, MCP, tools, and docs |\n| `transport/` | HTTP RPC, WebSocket, and static asset serving |\n| `cmd/nusashell/` | Composition root, configuration, lifecycle, and entrypoint |\n| `frontend/` | Embedded native JavaScript, CSS, HTML, and frontend tests |\n| `apps/electron/` | Cross-platform Electron wrapper, preload, packaging, and wrapper tests |\n| `testdata/` | Stable fixtures, including a fake stdio MCP server |\n\nThe web shell starts at `frontend/page/conversation/app.js`; feature controllers live in `frontend/page/`, thread instruments in `frontend/widgets/`, and shared browser helpers in `frontend/js/`. The previous interface is retained locally at `.experimental/old-frontend/`.\n\nThe routing matrix and static-serving policies live in\n[`docs/architecture.md`](docs/architecture.md).\n\n## Contributing\n\nPlease keep changes focused, preserve the dependency direction described in\n[`AGENTS.md`](AGENTS.md), add or update tests for changed behavior, and run the\nverification commands relevant to the change. Pull requests can use the\nrepository template at [`.github/pull_request_template.md`](.github/pull_request_template.md).\n\n## Recent changes\n\nNotable additions, removals, and breaking changes live in\n[`CHANGELOG.md`](CHANGELOG.md). The current `[Unreleased]` section covers the\nPWA-grade shell, deterministic hydration placement, the dispatcher-family\ntool refactor, and the experience-learning system (JSONL growth stores,\nsignal-triggered jobs, always-injected profile documents).\n\n## License\n\nNusaShell is released under the [MIT License](LICENSE).\n"}