Experimental, early beta. Data model and interfaces are unstable; expect breaking changes between releases.

Install Noumenon

One command to install. Then point it at any git repository and ask questions.

Quickstart

1

Install the Launcher

curl -sSL https://noumenon.leifericf.com/install | bash

Installs the noum launcher to ~/.local/bin and verifies its checksum.

2

Run the Demo

noum demo

Downloads a pre-built knowledge graph for the noumenon repo itself (Noumenon imports its own source as the demo). The tarball is fetched from GitHub Releases, SHA256-verified, and extracted into ~/.noumenon/data/. No LLM credentials needed for queries — the analyze stage is already done.

Try:

noum ask noumenon "What are the major components?"
noum ask noumenon "Which files have the most churn?"
noum query hotspots noumenon
3

Ask a Question About Your Own Code

noum ask /path/to/your/repo "Where is auth handled?"

First call digests the repo (one-time). Subsequent calls reuse the graph.

Package Managers

Prefer a package manager? Noumenon ships through Homebrew, Scoop, and Docker. All channels track the same release artifacts.

Homebrew (macOS, Linux)

brew install leifericf/noumenon/noumenon

Scoop (Windows)

scoop bucket add leifericf https://github.com/leifericf/scoop-bucket
scoop install noumenon

Docker

docker run --rm -v $PWD:/repo ghcr.io/leifericf/noumenon ask /repo "..."

For full server-mode deployments (shared graphs, role-based tokens), see Run as a shared service.

Configure an LLM Endpoint

Noumenon needs an LLM API key for the analyze, synthesize, and ask stages. Demo data works without one, but real repos do not.

Point Noumenon at any endpoint that speaks the Anthropic Messages API: Anthropic directly, a router like OpenRouter or self-hosted LiteLLM, or any compatible gateway. Three env vars, two of them required:

  • NOUMENON_LLM_BASE_URL — endpoint URL (required)
  • NOUMENON_LLM_API_KEY — bearer/x-api-key value (required)
  • NOUMENON_LLM_MODEL — default model id, overridable per-call with --model (optional)

Anthropic directly

export NOUMENON_LLM_BASE_URL=https://api.anthropic.com
export NOUMENON_LLM_API_KEY=sk-ant-...
export NOUMENON_LLM_MODEL=claude-sonnet-4-6-20250514

OpenRouter (multi-model routing)

export NOUMENON_LLM_BASE_URL=https://openrouter.ai/api/v1
export NOUMENON_LLM_API_KEY=sk-or-...
export NOUMENON_LLM_MODEL=anthropic/claude-sonnet-4-5

LiteLLM (self-hosted proxy)

export NOUMENON_LLM_BASE_URL=http://localhost:4000
export NOUMENON_LLM_API_KEY=sk-litellm-master-...
export NOUMENON_LLM_MODEL=<the-name-defined-in-litellm-config.yaml>

For local use, noum setup will prompt for these and write them to ~/.noumenon/credentials. Noumenon reads that file directly — no shell sourcing needed.

Noumenon does not validate or alias the model id. Whatever you pass goes verbatim to the upstream endpoint.

Other Ways to Drive It

The same daemon answers to several front-ends. Pick whichever fits the moment:

  • Interactive TUI. Run noum with no arguments for a menu-driven terminal interface. Repos and ask sessions populate from live data, so there's nothing to memorize.
  • Desktop UI (experimental). noum open auto-downloads an early Electron preview with a graph view, drill-down, and a floating Ask overlay. Very rough — fine for poking around, not for daily driving. See Desktop UI.
  • Model Context Protocol. noum setup desktop or noum setup code wires Noumenon into Claude Desktop or Claude Code. Agents call noumenon_ask, noumenon_query, and a couple dozen other tools without loading raw source into context. See MCP setup.
  • HTTP API. Headless integrations talk plain JSON to the daemon. See the HTTP API reference.

Hit a snag? Open an issue or check the changelog for recent breaking changes.