npcsh 1.1.20__py3-none-any.whl → 1.1.22__py3-none-any.whl

{npcsh-1.1.20.dist-info → npcsh-1.1.22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: npcsh
-Version: 1.1.20
+Version: 1.1.22
 Summary: npcsh is a command-line toolkit for using AI agents in novel ways.
 Home-page: https://github.com/NPC-Worldwide/npcsh
 Author: Christopher Agostino
@@ -47,6 +47,7 @@ Requires-Dist: mcp
 Provides-Extra: lite
 Requires-Dist: anthropic; extra == "lite"
 Requires-Dist: openai; extra == "lite"
+Requires-Dist: ollama; extra == "lite"
 Requires-Dist: google-generativeai; extra == "lite"
 Requires-Dist: google-genai; extra == "lite"
 Provides-Extra: local
@@ -72,6 +73,7 @@ Requires-Dist: terminal-bench; extra == "bench"
 Provides-Extra: all
 Requires-Dist: anthropic; extra == "all"
 Requires-Dist: openai; extra == "all"
+Requires-Dist: ollama; extra == "all"
 Requires-Dist: google-generativeai; extra == "all"
 Requires-Dist: google-genai; extra == "all"
 Requires-Dist: sentence_transformers; extra == "all"
@@ -108,46 +110,31 @@ Dynamic: summary
 
 # npcsh
 
-The NPC shell (`npcsh`) makes the most of multi-modal LLMs and agents through a powerful set of simple slash  commands and novel interactive modes, all from the comfort of the command line. Build teams of agents and schedule them on jobs, engineer context, and design custom interaction modes and Jinja Execution templates (Jinxs for you and your agents to invoke, all managed scalably for organizations of any size through the NPC data layer.
+The NPC shell (`npcsh`) makes the most of multi-modal LLMs and agents through a powerful set of simple slash commands and novel interactive modes, all from the comfort of the command line. Build teams of agents and schedule them on jobs, engineer context, and design custom interaction modes and Jinja Execution templates (Jinxs) for you and your agents to invoke, all managed scalably for organizations of any size through the NPC data layer.
 
 To get started:
-For users who want to mainly use models through APIs (`ollama`, `gemini`, `kimi`, `grok`, `deepseek`, `anthropic`, `openai`, `mistral`, or any others provided by litellm )
 ```bash
-pip install 'npcsh[lite]' 
-```
-For users who want to use and fine-tune local models (this installs `diffusers`/`transformers`/`torch` stack so it is big):
+# API providers (ollama, gemini, kimi, grok, deepseek, anthropic, openai, mistral, etc.)
+pip install 'npcsh[lite]'
 
-```bash
+# Local models (diffusers/transformers/torch — large install)
 pip install 'npcsh[local]'
-```
-
 
-For users who want to use the voice mode `yap` (see also the OS-specific installation instructions for installing needed system audio  libraries)
-```bash
+# Voice mode (see OS-specific audio library instructions below)
 pip install 'npcsh[yap]'
-```
 
-Once installed: run
-```bash
-npcsh
+# Everything
+pip install 'npcsh[all]'
 ```
-and you will enter the NPC shell. 
-
-If you do not have any local models
 
-
-
-Additionally, the pip installation includes the following CLI tools available in bash: `npc` cli, `wander`, `spool`, `yap`, and `nql`. Bin jinxs in `npc_team/jinxs/bin/` are automatically registered as CLI commands. 
+Once installed, run `npcsh` to enter the NPC shell. The pip installation also provides the CLI tools `npc`, `wander`, `spool`, `yap`, and `nql` in your shell. Bin jinxs in `npc_team/jinxs/bin/` are automatically registered as additional CLI commands.
 
 
 # Usage
-  - Get help with a task: 
+  - Get help with a task:
       ```bash
-      npcsh>can you help me identify what process is listening on port 5337? 
+      npcsh>can you help me identify what process is listening on port 5337?
       ```
-      <p align="center"> 
-        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/port5337.png" alt="example of running npcsh to check what processes are listening on port 5337", width=600>
-      </p>
 
   - Edit files
       ```bash
@@ -155,68 +142,70 @@ Additionally, the pip installation includes the following CLI tools available in
       ```
 
 
-  - **Search**
-    - search the web
+  - **Search & Knowledge**
     ```bash
-    /search "cerulean city" perplexity
-
+    /web_search "cerulean city"            # Web search
+    /db_search "query"                     # Database search
+    /file_search "pattern"                 # File search
+    /memories                              # Interactive memory browser TUI
+    /kg                                    # Interactive knowledge graph TUI
+    /kg sleep                              # Evolve the knowledge graph
+    /kg dream                              # Creative synthesis across domains
+    /nql                                   # Database query TUI
     ```
     <p align="center">
-        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/search.gif" alt="example of search results", width=600>
+        <img src="gh_images/Screenshot%20from%202026-01-29%2015-02-52.png" alt="Web search results", width=600>
+    </p>
+    <p align="center">
+        <img src="gh_images/kg_facts_viewer.png" alt="Knowledge Graph TUI", width=500>
+    </p>
+    <p align="center">
+        <img src="gh_images/nql_menu.png" alt="NQL data browser", width=500>
+        <img src="gh_images/nql_table.png" alt="NQL table viewer", width=500>
     </p>
-    
-    - search approved memories
-    ```bash
-    /search query="how to deploy python apps" memory=true
-    ```
-        
-    - search the knowledge graph
-
-    ```bash
-    /search query="user preferences for database" kg=true
-    ```
-        
-    - execute a RAG search across files
 
-    ```bash
-    /search --rag -f ~/docs/api.md,~/docs/config.yaml "authentication setup"
-    ```
-        
-    - brainblast search (searches many keyword combinations)
+  - **Computer Use**
 
     ```bash
-    /search query="git commands" brainblast=true
+    /plonk 'find out the latest news on cnn' gemma3:12b ollama
     ```
-        
-    - web search with specific provider
-
-    ```bash
-    /search query="family vacations" sprovider="perplexity"
-    ```     
+    <p align="center">
+        <img src="gh_images/plonk.png" alt="Plonk GUI automation TUI", width=500>
+    </p>
 
-  - **Computer Use**
+  - **Generate Images with Vixynt**
 
     ```bash
-    /plonk 'find out the latest news on cnn' gemma3:12b ollama
+    /vixynt
     ```
+    <p align="center">
+        <img src="gh_images/vixynt.png" alt="Vixynt Image Creation Studio", width=500>
+    </p>
 
-  - **Generate Image**
+  - Generate images directly
     ```bash
     /vixynt 'generate an image of a rabbit eating ham in the brink of dawn' model='gpt-image-1' provider='openai'
     ```
       <p align="center">
-        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/rabbit.PNG" alt="a rabbit eating ham in the bring of dawn", width=250>
+        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/rabbit.PNG" alt="a rabbit eating ham in the bring of dawn", width=350>
       </p>
-  - **Generate Video**
+  - **Generate Videos**
+
+    ```bash
+    /roll
+    ```
+
+  - Generate videos directly
+
     ```bash
     /roll 'generate a video of a hat riding a dog' veo-3.1-fast-generate-preview  gemini
     ```
 
       <p align="center">
-        <img src="https://raw.githubusercontent.com/NPC-Worldwide/npcsh/main/test_data/hatridingdog.gif" alt="video of a hat riding a dog", width=250>
+        <img src="https://raw.githubusercontent.com/NPC-Worldwide/npcsh/main/test_data/hatridingdog.gif" alt="video of a hat riding a dog", width=350>
       </p> 
 
-  - **Serve an NPC Team** (Agentic API Server)
+  - **Serve an NPC Team**
     ```bash
     /serve --port 5337 --cors='http://localhost:5137/'
     ```
@@ -233,42 +222,20 @@ Additionally, the pip installation includes the following CLI tools available in
     ```bash
     /ots
     ```
-  - **Use an mcp server**: make use of NPCs with MCP servers.
+  - **MCP-powered agentic shell**: full tabbed TUI with chat, tool management, and server controls.
     ```bash
-    /corca --mcp-server-path /path.to.server.py
-    ```
-
-  - **Build an NPC Team**:
-
-    ``` bash
-    npc build flask --output ./dist --port 5337
-    npc build docker --output ./deploy
-    npc build cli --output ./bin
-    npc build static --api_url https://api.example.com
+    /corca
+    /corca mcp_server_path=/path/to/server.py
     ```
 
-  - **NQL - AI-Powered SQL Models**:
-    Run SQL models with embedded AI transformations using NPC agents:
+  - **Build an NPC Team**: Generate deployment artifacts for your team.
     ```bash
-    # List available models
-    nql show=1
-
-    # Run all models in dependency order
-    nql
-
-    # Run a specific model
-    nql model=daily_summary
-
-    # Schedule with cron (runs daily at 6am)
-    nql install_cron="0 6 * * *"
+    /build target=flask outdir=./dist port=5337
+    /build target=docker outdir=./deploy
+    /build target=cli outdir=./bin
+    /build target=static outdir=./site
     ```
 
-  - **Visualize Team Structure**:
-    ```bash
-    npc teamviz save=team_structure.png
-    ```
-    Generates network and ordered views showing NPCs, jinxs, and their relationships.
-
 # NPC Data Layer
 
 The core of npcsh's capabilities is powered by the NPC Data Layer. Upon initialization, a user will be prompted to make a team in the current directory or to use a global team stored in `~/.npcsh/` which houses the NPC team with its jinxs, models, contexts, assembly lines. By implementing these components as simple data structures, users can focus on tweaking the relevant parts of their multi-agent systems.
@@ -306,15 +273,19 @@ jinxs:
   - lib/core/python
   - lib/core/sh
   - lib/core/edit_file
-  - lib/core/search
+  - lib/core/load_file
 ```
 
 When an NPC is invoked, they can only use the jinxs assigned to them. This creates **specialization**:
-- `corca` has coding tools (python, sh, edit_file)
-- `plonk` has browser automation (browser_action, screenshot)
-- `alicanto` has research tools (arxiv, semantic_scholar, paper_search)
+- `corca` has coding tools (python, sh, edit_file, load_file)
+- `plonk` has browser automation (browser_action, screenshot, click)
+- `alicanto` has research tools (python, sh, load_file)
 - `frederic` has generation tools (vixynt, roll, sample)
 
+<p align="center">
+    <img src="gh_images/team_npc.png" alt="NPC team browser", width=700>
+</p>
+
 The forenpc (orchestrator) can delegate to any team member based on their specialization.
 
 ## Delegation with Review Loop
@@ -347,6 +318,15 @@ The `/delegate` jinx sends a task to another NPC with automatic review and feedb
    task complete
 ```
 
+## Deep Research with Alicanto
+
+The `/alicanto` mode runs multi-agent deep research — generates hypotheses, assigns persona-based sub-agents, runs iterative tool-calling loops, and synthesizes findings.
+
+<p align="center">
+    <img src="gh_images/alicanto.png" alt="Alicanto deep research mode", width=500>
+    <img src="gh_images/alicanto_2.png" alt="Alicanto execution phase", width=500>
+</p>
+
 ## Convening Multi-NPC Discussions
 
 The `/convene` jinx brings multiple NPCs together for a structured discussion:
@@ -391,6 +371,10 @@ This generates two views:
 
 Shared jinxs (like `python` used by 7 NPCs) appear with thicker connection bundles, helping you identify common capabilities and potential consolidation opportunities.
 
+<p align="center">
+    <img src="gh_images/teamviz.png" alt="Team structure visualization", width=700>
+</p>
+
 # NQL - SQL Models with AI Functions
 
 NQL (NPC Query Language) enables AI-powered data transformations directly in SQL, similar to dbt but with embedded LLM calls. Create `.sql` files in `npc_team/models/` that combine standard SQL with `nql.*` AI function calls, then run them on a schedule to build analytical tables enriched with AI insights.
@@ -550,93 +534,115 @@ The NPC responds using their persona and available jinxs, then control returns t
 
 | NPC | Specialty | Key Jinxs |
 |-----|-----------|-----------|
-| `sibiji` | Orchestrator/coordinator | delegate, convene, search |
-| `corca` | Coding and development | python, sh, edit_file, search |
-| `plonk` | Browser/GUI automation | browser_action, screenshot, click |
-| `alicanto` | Research and analysis | arxiv, semantic_scholar, paper_search |
-| `frederic` | Math, physics, music | python, vixynt, roll, sample, wander |
-| `guac` | General assistant | python, sh, search |
-| `kadiefa` | Creative generation | vixynt, roll, wander |
+| `sibiji` | Orchestrator/coordinator | delegate, convene, python, sh |
+| `corca` | Coding and development | python, sh, edit_file, load_file |
+| `plonk` | Browser/GUI automation | browser_action, screenshot, click, key_press |
+| `alicanto` | Research and analysis | python, sh, load_file |
+| `frederic` | Math, physics, music | python, vixynt, roll, sample |
+| `guac` | General assistant | python, sh, edit_file, load_file |
+| `kadiefa` | Creative generation | vixynt |
+
+<p align="center">
+    <img src="gh_images/npc_menu.png" alt="NPC menu", width=700>
+</p>
 
 # Jinxs (Macros/Tools)
 
-Jinxs are reusable tools that NPCs can invoke. They're activated with `/<jinx_name> ...` in npcsh or via the `npc` CLI in bash. For converting any `/<command>` in npcsh to bash, replace `/` with `npc `:
+Jinxs are reusable tools that users and agents can invoke. They're activated with `/<jinx_name> ...` in npcsh or via the `npc` CLI in bash. For converting any `/<command>` in npcsh to bash, replace `/` with `npc `:
 
 ```bash
 # In npcsh:
-/vixynt "a sunset over mountains"
+/sample "tell me a story about a sunset over the mountains"
 
 # In bash:
-npc vixynt "a sunset over mountains"
+npc sample "a sunset over mountains"
 ```
 
-## Jinx Commands
+## All Commands
 
-### Orchestration & Research
 | Command | Description |
 |---------|-------------|
-| `/alicanto` | Deep research with multiple perspectives. Usage: `/alicanto 'query' --num-npcs 3 --depth 2` |
-| `/convene` | Multi-NPC structured discussion. Usage: `/convene "topic" --npcs corca,guac --rounds 3` |
-| `/delegate` | Delegate task to NPC with review loop. Usage: `/delegate npc_name=corca task="..." max_iterations=5` |
-| `/search` | Web/memory/knowledge graph search. Usage: `/search 'query' --sprovider perplexity` |
+| `/alicanto` | Multi-agent deep research — hypotheses, persona sub-agents, paper writing |
+| `/corca` | MCP-powered agentic shell — chat, tool management, server controls |
+| `/convene` | Multi-NPC structured discussion with live trains of thought |
+| `/spool` | Chat session with fresh context, file attachments, and RAG |
+| `/pti` | Pardon-the-interruption reasoning mode |
+| `/plonk` | GUI automation with vision |
+| `/wander` | Exploratory thinking with temperature shifts |
+| `/yap` | Voice chat — continuous VAD listening, auto-transcribe, TTS |
+| `/guac` | Interactive Python REPL with LLM code generation |
+| `/kg` | Knowledge graph browser — facts, concepts, links, search, graph |
+| `/kg sleep` | Evolve knowledge graph through consolidation |
+| `/kg dream` | Creative synthesis across KG domains |
+| `/memories` | Memory browser — browse, approve, reject, filter by status |
+| `/nql` | Database browser and NQL SQL model runner |
+| `/papers` | Multi-platform research paper browser |
+| `/arxiv` | ArXiv paper browser |
+| `/git` | Git integration TUI |
+| `/build` | Build team to deployable format (flask, docker, cli, static) |
+| `/team` | Team config browser — context, NPCs, jinxs |
+| `/config_tui` | Interactive config editor |
+| `/reattach` | Resume previous conversation sessions |
+| `/delegate` | Delegate task to NPC with review loop |
+| `/web_search` | Web search |
+| `/db_search` | Database search |
+| `/file_search` | File search |
+| `/vixynt` | Generate/edit images |
+| `/roll` | Generate videos |
+| `/sample` | Context-free LLM prompt |
+| `/serve` | Serve NPC team as API with OpenAI-compatible endpoints |
+| `/compile` | Compile NPC profiles |
+| `/set` | Set config values — `/set model gemma3:4b`, `/set provider ollama` |
+| `/teamviz` | Visualize team structure |
+| `/ots` | Screenshot analysis |
+| `/models` | Browse available models |
+| `/chat` | Switch to chat mode |
+| `/cmd` | Switch to command mode |
+| `/switch` | Switch NPC |
+| `/sync` | Sync npc_team files from repo to home |
+
+Most commands launch full-screen TUIs — just type and interact. For CLI usage with `npc`, common flags include `--model (-mo)`, `--provider (-pr)`, `--npc (-np)`, and `--temperature (-t)`. Run `npc --help` for the full list.
+
+### `/wander` — Creative Exploration
+Wander mode shifts the model's temperature up and down as it explores a problem, producing divergent ideas followed by convergent synthesis. The live TUI dashboard shows the current temperature, accumulated thoughts, and a running summary.
 
-### Generation
-| Command | Description |
-|---------|-------------|
-| `/vixynt` | Generate/edit images. Usage: `/vixynt 'description' --igmodel gpt-image-1 --igprovider openai` |
-| `/roll` | Generate videos. Usage: `/roll 'description' --vgmodel veo-3.1-fast-generate-preview --vgprovider gemini` |
-| `/sample` | Context-free LLM prompt. Usage: `/sample 'question' -m gpt-4o-mini --temp 0.7` |
+<p align="center">
+    <img src="gh_images/wander.png" alt="Wander TUI", width=500>
+</p>
 
-### Modes & Sessions
-| Command | Description |
-|---------|-------------|
-| `/spool` | Interactive chat with fresh context/RAG. Usage: `/spool --attachments 'file1,file2' -n corca` |
-| `/yap` | Voice chat mode. Usage: `/yap -n frederic` |
-| `/pti` | Pardon-the-interruption reasoning mode. Usage: `/pti` |
-| `/plonk` | GUI automation with vision. Usage: `/plonk 'click the submit button'` |
-| `/wander` | Exploratory thinking with temperature shifts. Usage: `/wander 'query' --model deepseek-r1:32b` |
+### `/guac` — Interactive Python REPL
+Guac is an LLM-powered Python REPL with a live variable inspector, DataFrame viewer, and inline code execution. Describe what you want in natural language and the model writes and runs the code. Variables persist across turns.
 
-### Data & Analytics
-| Command | Description |
-|---------|-------------|
-| `/nql` | Run NQL SQL models. Usage: `/nql show=1`, `/nql model=daily_summary` |
-| `/teamviz` | Visualize team structure. Usage: `/teamviz save=output.png` |
-| `/ots` | Screenshot analysis. Usage: `/ots` then select area |
-| `/sleep` | Evolve knowledge graph. Usage: `/sleep --ops link_facts,deepen` |
-| `/kg_search` | Search knowledge graph with multiple modes. Usage: `/kg_search query mode=hybrid depth=2` |
-| `/mem_search` | Search approved memories. Usage: `/mem_search query status=approved top_k=10` |
-| `/mem_review` | Review pending memories interactively. Usage: `/mem_review limit=50` |
-
-### System & Config
-| Command | Description |
-|---------|-------------|
-| `/build` | Build team to deployable format. Usage: `/build docker --output ./deploy` |
-| `/serve` | Full agentic server with NPC management, jinx controls, and OpenAI-compatible endpoints. Usage: `/serve --port 5337` |
-| `/compile` | Compile NPC profiles. Usage: `/compile path/to/npc` |
-| `/init` | Initialize NPC project. Usage: `/init` |
-| `/set` | Set config values. Usage: `/set model gemma3:4b`, `/set provider ollama` |
-| `/help` | Show help. Usage: `/help` |
-| `/jinxs` | List available jinxs. Usage: `/jinxs` |
-| `/incognide` | Launch Incognide GUI. Usage: `/incognide` |
-| `/trigger` | Set up system triggers. Usage: `/trigger 'description' -m gemma3:27b` |
-    
-    ## Common Command-Line Flags:
-    
-    ```
-    Flag              Shorthand    | Flag              Shorthand    | Flag              Shorthand    | Flag              Shorthand   
-    ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------
-    --attachments     (-a)         | --height          (-h)         | --num_npcs        (-num_n)     | --team            (-tea)      
-    --config_dir      (-con)       | --igmodel         (-igm)       | --output_file     (-o)         | --temperature     (-t)      
-    --cors            (-cor)       | --igprovider      (-igp)       | --plots_dir       (-pl)        | --top_k                       
-    --creativity      (-cr)        | --lang            (-l)         | --port            (-po)        | --top_p                       
-    --depth           (-d)         | --max_tokens      (-ma)        | --provider        (-pr)        | --vmodel          (-vm)       
-    --emodel          (-em)        | --messages        (-me)        | --refresh_period  (-re)        | --vprovider       (-vp)       
-    --eprovider       (-ep)        | --model           (-mo)        | --rmodel          (-rm)        | --width           (-w)        
-    --exploration     (-ex)        | --npc             (-np)        | --rprovider       (-rp)        |                               
-    --format          (-f)         | --num_frames      (-num_f)     | --sprovider       (-s)         |                               
-    ```
+<p align="center">
+    <img src="gh_images/guac_session.png" alt="Guac Python REPL", width=500>
+</p>
 
-## Memory & Knowledge Graph
+### `/arxiv` — Paper Browser
+Browse, search, and read arXiv papers from the terminal. The TUI shows search results, full paper metadata, and rendered abstracts with j/k navigation and Enter to drill in.
+
+<p align="center">
+    <img src="gh_images/arxiv_search.png" alt="ArXiv search", width=500>
+    <img src="gh_images/arxiv_paper.png" alt="ArXiv paper view", width=500>
+</p>
+<p align="center">
+    <img src="gh_images/arxiv_abs.png" alt="ArXiv abstract view", width=700>
+</p>
+
+### `/reattach` — Session Browser
+Resume previous conversation sessions. The TUI lists past sessions with timestamps and previews — select one to pick up where you left off.
+
+<p align="center">
+    <img src="gh_images/Screenshot%20from%202026-01-29%2014-43-20.png" alt="Reattach session browser", width=500>
+</p>
+
+### `/models` — Model Browser
+Browse all available models across providers (Ollama, OpenAI, Anthropic, etc.), see which are currently active, and set new defaults interactively.
+
+<p align="center">
+    <img src="gh_images/models.png" alt="Models browser", width=500>
+</p>
+
+# Memory & Knowledge Graph
 
 `npcsh` maintains a memory lifecycle system that allows agents to learn and grow from past interactions. Memories progress through stages and can be incorporated into a knowledge graph for advanced retrieval.
 
@@ -650,67 +656,52 @@ Memories are extracted from conversations and follow this lifecycle:
 4. **human-edited** - Modified by user before approval
 5. **skipped** - Deferred for later review
 
-### Memory Commands
-
-```bash
-# Search through approved memories
-/mem_search python                      # Keyword search
-/mem_search python status=approved      # Filter by status
-/mem_search python top_k=20             # Limit results
-
-# Review pending memories interactively
-/mem_review                             # Review with default limit
-/mem_review limit=50                    # Review more at once
-```
-
-### Knowledge Graph
+### Memories
 
-The knowledge graph stores facts and concepts extracted from approved memories, enabling semantic search and reasoning. Facts are linked to concepts, allowing traversal-based discovery.
+The `/memories` command opens an interactive TUI for browsing, reviewing, and managing memories:
 
 ```bash
-# Keyword search
-/kg_search python                       # Simple keyword match
-
-# Semantic similarity search
-/kg_search python mode=embedding        # Find semantically similar facts
-
-# Graph traversal search
-/kg_search python mode=link depth=3     # Traverse graph links
-
-# Hybrid search (combines methods)
-/kg_search python mode=all              # All methods combined
-
-# Explore concepts
-/kg_search type=concepts                # List all concepts
-/kg_search concept="Machine Learning"   # Explore a specific concept
+/memories
 ```
 
-### Knowledge Graph Evolution
+The TUI provides:
+- **Tab-based filtering** — switch between All, Pending, Approved, Rejected, etc.
+- **Approve/Reject** — press `a` to approve, `x` to reject
+- **Preview** — press Enter to see full memory content
+- **Session stats** — tracks approvals/rejections during session
 
-The `/sleep` command evolves the knowledge graph through consolidation, abstraction, and creative synthesis:
+<p align="center">
+    <img src="gh_images/Screenshot%20from%202026-01-29%2016-03-08.png" alt="Memory Browser TUI", width=700>
+</p>
 
-```bash
-# Basic sleep (consolidation)
-/sleep
+### Knowledge Graph
 
-# Import approved memories first, then evolve
-/sleep backfill=true
+The `/kg` command opens an interactive browser for exploring the knowledge graph:
 
-# Dream mode - creative synthesis across domains
-/sleep dream=true
+```bash
+/kg                     # Browse facts, concepts, links, search, graph view
+/kg sleep               # Evolve KG through consolidation
+/kg dream               # Creative synthesis across domains
+/kg evolve              # Alias for sleep
+/kg sleep backfill=true # Import approved memories first, then evolve
+/kg sleep ops=prune,deepen,abstract  # Specific operations
+```
 
-# Combined backfill and dream
-/sleep backfill=true dream=true
+The TUI browser has 5 tabs: **Facts**, **Concepts**, **Links**, **Search**, and **Graph** — navigate with Tab, j/k, and Enter to drill into details.
 
-# Specific operations
-/sleep ops=prune,deepen,abstract
-```
+<p align="center">
+    <img src="gh_images/kg_facts_viewer.png" alt="Knowledge Graph Facts", width=500>
+    <img src="gh_images/kg_links.png" alt="Knowledge Graph Links", width=500>
+</p>
+<p align="center">
+    <img src="gh_images/kg_viewer.png" alt="Knowledge Graph Viewer", width=700>
+</p>
 
-**Operations:**
-- **prune** - Remove redundant or low-value facts
-- **deepen** - Add detail to existing facts
-- **abstract** - Create higher-level generalizations
-- **link** - Connect related facts and concepts
+**Evolution operations** (via `/kg sleep` or `/sleep`):
+- **prune** — Remove redundant or low-value facts
+- **deepen** — Add detail to existing facts
+- **abstract** — Create higher-level generalizations
+- **link** — Connect related facts and concepts
 
 ### Environment Variables
 
@@ -722,28 +713,20 @@ export NPCSH_BUILD_KG=1
 export NPCSH_DB_PATH=~/npcsh_history.db
 ```
 
-## Read the Docs
-To see more about how to use the jinxs and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
-
+Full documentation: [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
 
-## Inference Capabilities
-- `npcsh` works with local and enterprise LLM providers through its LiteLLM integration, allowing users to run inference from Ollama, LMStudio, vLLM, MLX, OpenAI, Anthropic, Gemini, and Deepseek, making it a versatile tool for both simple commands and sophisticated AI-driven tasks. 
+`npcsh` works with local and enterprise LLM providers through LiteLLM — Ollama, LMStudio, vLLM, MLX, OpenAI, Anthropic, Gemini, Deepseek, and more.
 
 ## Incognide
-Incognide is a desktop workspace environment for integrating LLMs into your workflows in an organized and seamless manner. See the source code for Incognide [here](https://github.com/npc-worldwide/incognide). Download the executables at [our website](https://enpisi.com/downloads). For the most up to date development version, you can use Incognide by invoking it in npcsh 
 
-```
-/incognide
-```
-which will download and set up and serve the Incognide application within your `~/.npcsh` folder. It requires `npm` and `node` to work, and of course npcpy !
-
-## Mailing List and Community
-Interested to stay in the loop and to hear the latest and greatest about `npcpy`, `npcsh`, and Incognide? Be sure to sign up for the [newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A)!
+[Incognide](https://github.com/npc-worldwide/incognide) is a desktop workspace environment for integrating LLMs into your workflows. [Download executables](https://enpisi.com/downloads) or run `/incognide` in npcsh to install and serve it locally (requires `npm` and `node`).
 
-[Join the discord to discuss ideas for npc tools](https://discord.gg/VvYVT5YC)
-## Support
-If you appreciate the work here, [consider supporting NPC Worldwide with a monthly donation](https://buymeacoffee.com/npcworldwide), [buying NPC-WW themed merch](https://enpisi.com/shop), [using and subscribing to Lavanzaro](lavanzaro.com),s or hiring us to help you explore how to use the NPC Toolkit and AI tools to help your business or research team, please reach out to info@npcworldwi.de .
+## Community & Support
 
+- [Newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A) — latest updates on `npcpy`, `npcsh`, and Incognide
+- [Discord](https://discord.gg/VvYVT5YC) — discuss ideas for NPC tools
+- [Buy us a coffee](https://buymeacoffee.com/npcworldwide) | [Merch](https://enpisi.com/shop) | [Lavanzaro](https://lavanzaro.com)
+- For consulting: info@npcworldwi.de
 
 ## Installation
 `npcsh` is available on PyPI and can be installed using pip. Before installing, make sure you have the necessary dependencies installed on your system. Below are the instructions for installing such dependencies on Linux, Mac, and Windows. If you find any other dependencies that are needed, please let us know so we can update the installation instructions to be more accommodating.
@@ -761,10 +744,6 @@ sudo apt-get install libcairo2-dev
 sudo apt-get install libgirepository1.0-dev
 sudo apt-get install ffmpeg
 
-# for triggers
-sudo apt install inotify-tools
-
-
 #And if you don't have ollama installed, use this:
 curl -fsSL https://ollama.com/install.sh | sh
 
@@ -796,10 +775,6 @@ brew install portaudio
 brew install ffmpeg
 brew install pygobject3
 
-# for triggers
-brew install inotify-tools
-
-
 brew install ollama
 brew services start ollama
 ollama pull llama3.2
@@ -912,51 +887,41 @@ export PERPLEXITY_API_KEY='your_perplexity_key'
 
  Individual npcs can also be set to use different models and providers by setting the `model` and `provider` keys in the npc files.
 
- Once initialized and set up, you will find the following in your `~/.npcsh` directory:
-```bash
-~/.npcsh/
-├── npc_team/              # Global NPC team
-│   ├── jinxs/
-│   │   ├── bin/           # CLI commands (wander, spool, yap, nql, vixynt, roll, sample)
-│   │   └── lib/           # Library jinxs by category
-│   │       ├── core/      # python, sh, sql, search, edit_file, load_file
-│   │       ├── browser/   # browser_action, screenshot
-│   │       ├── orchestration/  # delegate, convene
-│   │       └── research/  # arxiv, semantic_scholar, paper_search
-│   ├── models/            # NQL SQL models
-│   ├── assembly_lines/    # Workflow pipelines
-│   ├── sibiji.npc         # Orchestrator NPC
-│   ├── corca.npc          # Coding specialist
-│   ├── plonk.npc          # Browser automation
-│   ├── ...                # Other NPCs
-│   └── npcsh.ctx          # Team context (sets forenpc, team name)
-```
-For cases where you wish to set up a project specific set of NPCs, jinxs, and assembly lines, add a `npc_team` directory to your project and `npcsh` should be able to pick up on its presence, like so:
-```bash
-./npc_team/            # Project-specific NPCs
-├── jinxs/             # Project jinxs
-│   ├── bin/           # Standalone CLI commands (unique names, auto-registered)
-│   │   └── wander, spool, yap, nql, vixynt, roll, sample
-│   └── lib/           # Library jinxs organized by category
-│       ├── core/      # Core utilities (python, sh, sql, search, etc.)
-│       ├── browser/   # Browser automation
-│       ├── orchestration/  # delegate, convene
-│       └── research/  # Research tools (arxiv, semantic_scholar)
-├── models/            # NQL SQL models for AI-powered data pipelines
-│   ├── base/          # Base statistics models
-│   └── insights/      # Models with nql.* AI functions
-├── assembly_lines/    # Agentic Workflows
-│   └── example.line
-├── example1.npc       # Example NPC
-├── example2.npc       # Example NPC
-└── team.ctx           # Team context file
-
-
+ Once initialized, the global team lives in `~/.npcsh/npc_team/`. You can also create a project-specific team by adding an `npc_team/` directory to any project — npcsh picks it up automatically and overlays it on the global team.
+
+```
+npc_team/
+├── jinxs/
+│   ├── modes/            # TUI modes (alicanto, corca, kg, yap, etc.)
+│   ├── lib/
+│   │   ├── core/         # Core tools (python, sh, sql, edit_file, delegate, etc.)
+│   │   │   └── search/   # Search tools (web_search, db_search, file_search)
+│   │   ├── utils/        # Utility jinxs (set, compile, serve, teamviz, etc.)
+│   │   ├── browser/      # Browser automation (browser_action, screenshot, etc.)
+│   │   └── computer_use/ # Computer use (click, key_press, screenshot, etc.)
+│   └── incognide/        # Incognide desktop workspace jinxs
+├── models/               # NQL SQL models
+│   ├── base/             # Base statistics models
+│   └── insights/         # Models with nql.* AI functions
+├── assembly_lines/       # Workflow pipelines
+├── sibiji.npc            # Orchestrator NPC
+├── corca.npc             # Coding specialist
+├── ...                   # Other NPCs
+├── mcp_server.py         # MCP server for tool integration
+└── npcsh.ctx             # Team context (sets forenpc, team name)
 ```
 
+<p align="center">
+    <img src="gh_images/team_ui.png" alt="Team config browser", width=500>
+    <img src="gh_images/jinx_menu.png" alt="Jinx browser", width=500>
+</p>
+<p align="center">
+    <img src="gh_images/jinx_folder_viewer.png" alt="Jinx folder viewer", width=500>
+    <img src="gh_images/jinx_ui.png" alt="Jinx detail view", width=500>
+</p>
+
 ## Contributing
 Contributions are welcome! Please submit issues and pull requests on the GitHub repository.
 
-
 ## License
 This project is licensed under the MIT License.