Guac Mode Documentation

Guac mode is an interactive Python environment within the NPC Shell (npcsh) that combines code execution, LLM-powered code generation, and session-based automation. It is designed to help users work more efficiently by evolving with their workflow and providing periodic suggestions for automation.

What is Guac Mode?

Guac mode allows you to: - Execute Python code interactively, with variables and functions persisting across commands. - Use natural language to generate and execute Python code via LLMs. - Run shell-like commands (ls, cd, pwd, run <script.py>) directly in the REPL. - Switch between modes: cmd (direct code), chat (conversational), and agent (task routing). - Periodically "refresh" your session, where the LLM reviews your command history and suggests new helper functions, which you can add to your personal guac module.

Setup and Configuration

When you first run Guac mode, it creates a configuration directory at ~/.npcsh/guac/ with the following structure:

  • src/ — Your evolving main.py and helpers live here.
  • plots/ — Default directory for saving plots.
  • npc_team/ — Contains your personal NPCs and team context for LLM interactions.
  • config.json — Stores your preferred language, directories, and default mode.

Guac mode ensures these directories exist and initializes them with sensible defaults. Your main.py is pre-populated with common data science imports and helper functions for saving plots and viewing images.

Modes

  • cmd: Direct Python code execution or LLM-generated code from natural language prompts. No explanations, just code.
  • chat: Conversational mode for back-and-forth with the LLM.
  • agent: Task routing mode, where the LLM decides how to fulfill your request (code, tools, or chat).

Switch modes at any time with /cmd, /chat, or /agent.

Shell-like Commands

You can use commands like ls, cd, pwd, and run <script.py> directly in the Guac REPL. These are handled before Python code detection.

The Refresh Cycle

Guac mode uses a "cyclicality" mechanism: - As you work, a counter advances from 🥑 (fresh avocado) through several stages. - After a set number of commands, you are prompted to /refresh. - On refresh, the LLM reviews your recent commands and suggests 1–3 Python helper functions tailored to your workflow. - You can choose to add these helpers to your main.py, evolving your environment over time.

Example Session

🥑 ls
# Lists files in the current directory
🥑 cd npcpy
# Changes directory
🥑 print("Hello, world!")
# Executes Python code
🥑 What is the mean of [1,2,3,4]?
# LLM generates and executes code to compute the mean
🥑 /refresh
# LLM suggests new helper functions based on your session

Inspecting and Using Variables

All variables and functions you define (or that are generated by the LLM) persist in your session. Use /show_vars to list them.

Evolving Your Environment

Every time you accept a suggested helper from /refresh, it is appended to your main.py in ~/.npcsh/guac/src/. You can import and use these helpers immediately.

Quickstart

  1. Start npcsh and enter Guac mode: 
    npcsh
# then type: guac
  2. Work interactively, using Python, shell commands, or natural language.
  3. Use /refresh when prompted to evolve your environment.

Appendix: Example Transcript

(npcsh) caug@pop-os:/media/caug/extradrive1/npcww/npcsh$ guac gLoaded .env file from /media/caug/extradrive1/npcww/npcsh hows iloading npc team from directory Error loading team context: 'Team' object has no attribute 'jinja_env' filename: guac.npc filename: toon.npc filename: parsely.npc filename: caug.npc filename: team.ctx 🥑 hows it going

Generated python code:

print("I'm doing well, thank you! How can I assist you with Python today?")

I'm doing well, thank you! How can I assist you with Python today?

Generated code executed successfully

🥑 ls composition.png docs image.png Makefile mkdocs.yml npcpy.egg-info npcsh.code-workspace otter_.png pirate.png setup.py template_tests tests data examples LICENSE MANIFEST.in npcpy npcpy.png otter.png output_image.png README.md sprite.png test_data 🥑 cd npcpy Changed directory to /media/caug/extradrive1/npcww/npcsh/npcpy 🥑 ls data init.py main.py migrations modes npcsh.png npc_sysenv.py pycache sql gen llm_funcs.py memory mix npc_compiler.py npcs.py npc_team routes.py work 🥑 run llm_funcs.py Items added/modified from llm_funcs.py: subprocess: Generator: PIL: <module 'PIL' from '/home/caug/.pyenv/versions/3.11.0/envs/npcsh/lib/python3.11/site-packages/PIL/__... render_markdown: NPCSH_VIDEO_GEN_PROVIDER: 'diffusers' generate_image: NPCSH_IMAGE_GEN_PROVIDER: 'openai' Union: requests: <module 'requests' from '/home/caug/.pyenv/versions/3.11.0/envs/npcsh/lib/python3.11/site-packages/r... NPCSH_CHAT_MODEL: 'gpt-4.1-mini' rehash_last_message: generate_video: get_system_message: get_llm_response: Optional: FileSystemLoader: NPCSH_EMBEDDING_MODEL: 'nomic-embed-text' NPCSH_EMBEDDING_PROVIDER: 'ollama' NPCSH_VIDEO_GEN_MODEL: 'runwayml/stable-diffusion-v1-5' NPCSH_VISION_MODEL: 'gpt-4o-mini' NPCSH_VISION_PROVIDER: 'openai' sqlite3: check_llm_command: NPCSH_REASONING_MODEL: 'deepseek-reasoner' NPCSH_API_URL: '' NPCSH_REASONING_PROVIDER: 'deepseek' execute_llm_command: lookup_provider: Dict: create_engine: decide_plan: NPCSH_CHAT_PROVIDER: 'openai' get_litellm_response: Any: Undefined: NPCSH_IMAGE_GEN_MODEL: 'dall-e-2' Template: NPCSH_DEFAULT_MODE: 'chat' generate_image_litellm: handle_jinx_call: List: Environment:

🥑 out = get_llm_response('hello', model='gpt-4.1-mini', provider='openai') 🥑 print(out) {'response': 'Hello! How can I assist you today?', 'messages': [{'role': 'system', 'content': 'You are a helpful assistant.'}, {'role': 'user', 'content': [{'type': 'text', 'text': 'hello'}]}, {'role': 'assistant', 'content': 'Hello! How can I assist you today?'}], 'raw_response': ModelResponse(id='chatcmpl-BR2eVV5PUAgvyFLSZNUkbSUUG3tdI', created=1745784751, model='gpt-4.1-mini-2025-04-14', object='chat.completion', system_fingerprint='fp_38647f5e19', choices=[Choices(finish_reason='stop', index=0, message=Message(content='Hello! How can I assist you today?', role='assistant', tool_calls=None, function_call=None, provider_specific_fields={'refusal': None}, annotations=[]))], usage=Usage(completion_tokens=10, prompt_tokens=18, total_tokens=28, completion_tokens_details=CompletionTokensDetailsWrapper(accepted_prediction_tokens=0, audio_tokens=0, reasoning_tokens=0, rejected_prediction_tokens=0, text_tokens=None), prompt_tokens_details=PromptTokensDetailsWrapper(audio_tokens=0, cached_tokens=0, text_tokens=None, image_tokens=None)), service_tier='default'), 'tool_calls': []}

Guac lets users execute code snippets or to ask LLMs questions which respond by generating and executing code directly within the interpreter. The variables and functions generated during these executions are inspectable to the user. In addition, guac is set up to provide users with a sense of cyclicality by progressing from a raw avocado (🥑) through a series of intermediaite steps until it is a gross brown mush (🥘). At this point, the user is asked to refresh, which initiates an LLM review of the session's commands and results and then suggests automations and then after the user reviews them they will be added to the user's guac module that is installed locally within the ~/.npcsh/guac/ folder and which eveolves as the user uses it. This refresh period is meant to encourage frequent reviews for users to help them work more efficiently and cognizantly.