Reference

Environment Variables

All variables are optional unless noted. This list reflects the Bahulam CLI runtime environment.

Bahulam runtime

Variable	Description
`BAHULAM_HOME`	Override the Bahulam config directory (default: `~/.bahulam`)
`BAHULAM_CONFIG_DIR`	Alias for `BAHULAM_HOME`; config directory override
`BAHULAM_TOKEN`	Auth token — used in CI/CD and headless pipelines
`BAHULAM_PRODUCT`	Advanced compatibility override for product routing; normal CLI runs use Bahulam
`BAHULAM_MISSION`	Optional mission tag persisted with the session
`BAHULAM_NO_PREFLIGHT`	Skip the onboarding diagnostic on startup (`1` / `true`)
`BAHULAM_STATUS_BAR`	Toggle the status bar (`1` / `0`)
`BAHULAM_SCRATCH_ROOTS`	Comma-separated writable roots outside the CWD
`BAHULAM_PROMPT_BOTTOM_PADDING`	Blank rows below the prompt (default `1`)
`BAHULAM_LONG_RUNNING_TIMEOUT_MS`	Override the long-running-tool cutoff
`BAHULAM_STAGNATION_DETECTION` / `BAHULAM_STAGNATION_THRESHOLD`	Tune stagnation heuristics
`BAHULAM_TTY_MODE`	Scrollback-safe transcript mode; set to `stable` if fixed-dock redraws leak on your terminal
`TARANG_ENV`	Select backend environment: `local`, `treetop`, `production` (default)
`TARANG_VERBOSE`	Enable verbose mode (`1`)
`TARANG_YES`	Auto-approve all approval prompts (`1`)
`KEPLER_CONFIG_DIR`	Legacy alias for config directory override
`KEPLER_RECONNECT_MAX_ELAPSED_MS`	Max reconnect window for dropped streams (default `300000`)
`KEPLER_BLOCK_SEPARATOR`	Tool/content separator style: `space`, `dotted`, `off` (default `space`)

Local browser workspace

Variable	Description
`BAHULAM_LIBREOFFICE_PATH`	Preferred path to the local LibreOffice `soffice` executable for DOCX/PPTX/ODT/ODP conversion previews
`LIBREOFFICE_PATH`	Compatibility fallback for `BAHULAM_LIBREOFFICE_PATH`
`BAHULAM_LOCAL_SAVE_MAX_BYTES`	Maximum text-backed file size the browser workspace can save (default `2 MB`)
`BAHULAM_LOCAL_SAVE_MAX_BODY_BYTES`	Maximum browser save request body size
`BAHULAM_LOCAL_UPLOAD_MAX_BODY_BYTES`	Maximum browser upload request body size (default `140 MB`)

Model provider keys (BYOK)

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic direct access
`ANTHROPIC_MODEL`	Default Anthropic model ID
`OPENAI_API_KEY`	OpenAI direct access
`OPENAI_BASE_URL`	Override the OpenAI-compatible endpoint (e.g. self-hosted vLLM)
`OPENROUTER_API_KEY`	OpenRouter (multi-provider routing)
`GEMINI_API_KEY` / `GOOGLE_API_KEY`	Google Gemini access
`BRAVE_API_KEY`	Brave Search (used by the web-search tool)

Logging & debugging

Variable	Description
`DEBUG`	Namespace-scoped debug logging (e.g. `DEBUG=bahulam:*`)
`MCP_DEBUG`	Verbose MCP-transport logging
`NO_COLOR`	Disable ANSI colour output

Advanced / rare

Variable	Description
`AGENT_ID`	Identifies sub-agent processes (set automatically)
`CLAUDE_CODE_PERMISSION_MODE`	Legacy compatibility fallback for `--permission-mode`
`CLAUDE_CODE_MAX_CONTEXT_TOKENS` / `CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Legacy compatibility model I/O caps
`CLAUDE_CODE_STREAMING` / `CLAUDE_CODE_THINKING`	Legacy compatibility feature toggles
`CLAUDE_CODE_ENABLE_TASKS`	Enable the built-in task manager
`CLAUDE_CODE_DISABLE_CRON` / `CLAUDE_CODE_DISABLE_TELEMETRY`	Opt-outs
`CLAUDE_CODE_SUBAGENT_MODEL`	Legacy compatibility override for the model used by sub-agents

Files on Disk

`~/.bahulam/` (Global Config)

Path	Purpose
`~/.bahulam/auth`	Cached authentication token
`~/.bahulam/config.json`	Global preferences (default model, theme, etc.)
`~/.bahulam/keys/`	Encrypted API keys for BYOK providers
`~/.bahulam/skills/`	User-global installed skills
`~/.bahulam/projects/`	Per-project metadata
`~/.bahulam/history.jsonl`	Cross-session prompt history
`~/.bahulam/state.json`	Current session metadata
`~/.bahulam/local-service/sessions/`	Local browser workspace session metadata
`~/.bahulam/local-service/previews/`	Cached local PDF previews generated from Office documents

`.bahulam/` (Project-Local)

Run bahulam init in a project to scaffold this folder. Bahulam may also create runtime files in .bahulam/ as sessions run.

Path	Purpose
`.bahulam/BAHULAM.md`	Bahulam project memory loaded into context
`.bahulam/settings.json`	Project settings, environment entries, permissions, and hook configuration
`.bahulam/settings.local.json`	Gitignored local override for personal settings
`.bahulam/config.json`	Project policy for context loading, planning, tasks, HITL, and command defaults
`.bahulam/project.md`	Additional durable project notes
`.bahulam/style.md`	Code style and communication conventions
`.bahulam/hitl.md`	Human-in-the-loop approval guidance
`.bahulam/trust.json`	Project trust rules used by approval handling
`.bahulam/tasks/backlog.md`	Deferred work
`.bahulam/tasks/active.md`	Current work in progress
`.bahulam/tasks/blocked.md`	Work waiting on input or external state
`.bahulam/tasks/done.md`	Completed work
`.bahulam/agents/`	Project-local sub-agent YAML definitions
`.bahulam/skills/`	Project-local skill bundles
`.bahulam/commands/`	Project-local command templates as they become available
`.bahulam/approvals.log`	Runtime approval decision log
`.bahulam/sessions/`	Runtime session transcripts
`.bahulam/reports/`	Runtime mission/report artifacts
`.bahulam/index/`	Runtime code-search index cache

Keyboard Shortcuts

Bahulam’s REPL uses standard terminal keybindings plus a few extras.

Shortcut	Action
`Esc`	Cancel current execution
`Space`	Pause / resume execution
`↑` / `↓`	Navigate command history
`Ctrl+C`	Cancel current operation / exit
`Ctrl+D`	Exit REPL (same as `/quit`)
`Ctrl+L`	Clear terminal screen
`Ctrl+R`	Search command history (reverse)
`Tab`	Auto-complete commands and file paths
`Ctrl+U`	Clear current input line
`Ctrl+W`	Delete word before cursor
`Ctrl+A`	Move cursor to beginning of line
`Ctrl+E`	Move cursor to end of line

Exit Codes

Code	Meaning
`0`	Success — no errors
`1`	General error — check stderr
`2`	Authentication error — session expired or invalid
`3`	Configuration error — missing or invalid config
`4`	Model error — model not found or unavailable
`5`	Credit error — insufficient credits

Permission Modes

Set with --permission-mode <mode> to control approval behavior.

Mode	Description
`bypassPermissions`	No approval prompts — all tool calls proceed
`acceptEdits`	Auto-approve file edits, prompt for shell commands
`plan`	Block all write operations — read-only planning mode
`auto`	Use tier-based defaults (see risk tiers below)
`dontAsk`	Never prompt — reject anything not auto-approved

Risk Tiers

Every tool call is classified into one of eight tiers.

Tier	Behavior	Examples
`read`	Auto — proceeds silently	`read_file`, `search_code`, `grep`
`sensitive-read`	Prompt required	Reading `.env`, `.pem`, `secrets/*`
`local-edit`	Auto with checkpoint	`edit_file`, `write_file`
`shell-safe`	Auto — proceeds silently	`ls`, `cat`, `pwd`, `git status`
`shell-medium`	Prompt safe (Enter=approve)	`npm install`, `git add`, `pip install`
`shell-dangerous`	Prompt explicit (must type `y`)	`rm -rf`, `chmod -R`, `sudo`
`destructive`	Prompt explicit (must type `y`)	`delete_file`
`network`	Prompt safe (Enter=approve)	`curl`, `wget`, `git clone`

Resume Modes

When resuming a session with --resume, Bahulam selects a strategy based on context window size and conversation length.

Strategy	Behavior
`full`	Send the entire conversation transcript
`summary`	Send only a summary of the previous conversation
`summary+tail-10`	Summary + last 10 messages
`summary+tail-20`	Summary + last 20 messages

Event Types

The SSE stream between Bahulam and the backend emits these event types:

Event	Direction	Description
`content`	Backend → CLI	Full assistant message
`content_partial`	Backend → CLI	Streaming text delta
`tool_call`	Backend → CLI	Tool invocation request
`tool_result`	CLI → Backend	Tool execution result
`sub_agent`	Backend → CLI	Delegated agent completion, including tool counts and success
`error`	Either	Error event
`complete`	Backend → CLI	Session complete
`timeout`	CLI → Backend	Session timeout
`start`	CLI → Backend	Session start

Tool Catalog

Bahulam has 25+ built-in tools. The agent selects and invokes them automatically based on the task.

File I/O

Tool	Description
`read_file`	Read a file with line ranges
`read_files`	Read multiple files at once
`write_file`	Create or overwrite a file
`write_project`	Write multiple files at once
`edit_file`	Search-and-replace edit
`multi_edit`	Multi-file edits
`delete_file`	Delete a file
`ls`	List directory contents

Search

Tool	Description
`search_code`	Semantic search across project code
`search_files`	Regex search across files
`grep`	Fast regex search (ripgrep)
`glob`	Pattern-based file search
`analyze_code`	Get structured analysis of a file
`get_project_overview`	Get project structure overview
`get_file_info`	Get file metadata

Shell

Tool	Description
`bash`	Run shell commands
`tool_search`	Search available tools

Git

Tool	Description
`git_status`	Show git status
`git_diff`	Show git diff

Web

Tool	Description
`web_fetch`	Fetch URLs
`web_search`	Search the web

Agent

Tool	Description
`explore`	Spawn read-only code explorer
`plan`	Spawn planning agent
`verify`	Spawn verification agent
`debug`	Spawn debugging agent
`refactor`	Spawn bounded refactor agent
`delegate`	Delegate to a built-in or user-defined sub-agent
`agent_create`	Create a project-local sub-agent YAML template
`agent_sync`	Optionally publish project-local agent YAML to the backend

Skills

Tool	Description
`skill`	Execute a skill
`skills_list`	List available skills
`skill_view`	View a skill’s details

MCP (Model Context Protocol)

Tool	Description
`read_mcp_resource`	Read MCP resources
`mcp`	MCP tool calls

Scheduling

Tool	Description
`cron_create`	Create a cron job
`cron_delete`	Delete a cron job
`cron_list`	List cron jobs

Other

Tool	Description
`ask_user`	Ask the user a question
`send_message`	Send a message
`enter_worktree`	Enter a worktree
`exit_worktree`	Exit a worktree
`notebook_edit`	Edit Jupyter notebooks
`todo_write`	Write task items
`lsp`	Language server protocol
`remote_trigger`	Remote trigger

File Structure for the Bahulam NPM Package

bahulam/
├── bin/
│   └── cli.js            # Entry point for the `bahulam` command
├── src/
│   ├── terminal/
│   │   ├── main.mjs      # CLI entry, subcommand dispatch
│   │   ├── repl.mjs      # REPL loop, command parsing
│   │   ├── agents.mjs    # Built-in agent definitions (explore, review, architect)
│   │   ├── analytics.mjs # Sessions, stats, history subcommands
│   │   ├── init.mjs      # `bahulam init` — scaffold .bahulam/
│   │   └── skills.mjs    # `bahulam skills` — skill management
│   ├── agents/           # Agent team orchestration
│   ├── auth/             # Browser auth flow (bahulam.ai) + config
│   ├── config/           # CLI args, env, settings, memory, hooks
│   ├── context/          # AST parser, BM25 retriever, skeleton, symbol indexer
│   ├── core/             # Central logic (30+ modules)
│   ├── hooks/            # Hook engine
│   ├── local-service/    # Local browser workspace service, file previews, and browser relay
│   ├── mcp/              # MCP client + transports (SSE, WebSocket, SHTTP)
│   ├── onboarding/       # Preflight diagnostics
│   ├── permissions/      # Command classifier, injection check, path check, sandbox
│   ├── plugins/          # Plugin loader
│   ├── skills/           # Skill installer, loader, runner
│   ├── state/            # Orbit state, verbosity
│   ├── telemetry/        # Telemetry index
│   ├── tools/            # 25+ built-in tool implementations
│   └── ui/               # Approval, banner, commands, dock, formatter, icons
└── package.json

Data Flow

Terminal CLI

┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Terminal     │────▶│  Bahulam CLI      │────▶│  API Gateway     │
│  (REPL)       │     │  (Agent)         │     │  (Platform)      │
└──────────────┘     └────────┬─────────┘     └────────┬─────────┘
                              │                        │
                              ▼                        ▼
                       ┌──────────────┐       ┌──────────────────┐
                       │  Sub-Agents   │       │  Bahulam Gateway │
                       │  Built-in     │──────▶│  Platform/BYOK   │
                       │  User YAML    │       └────────┬─────────┘
                       └──────────────┘                ▼
                                              ┌──────────────────┐
                                              │  Model Providers │
                                              │  OpenRouter etc. │
                                              └──────────────────┘

You type a request in the REPL
Bahulam builds the primary workspace agent from runtime config
If needed, the primary agent delegates to built-in or user-defined sub-agents
The orchestrator generates code changes via tool calls
Each tool call is classified by risk tier and approved accordingly
Changes are applied to your files
Results are reported back in the terminal

Local browser workspace

┌──────────────┐     ┌──────────────────┐     ┌──────────────────────┐
│  Browser      │────▶│  Local Service    │────▶│  CLI-authenticated   │
│  127.0.0.1    │     │  127.0.0.1        │     │  remote agent path   │
└──────────────┘     └────────┬─────────┘     └──────────┬───────────┘
                              │                          │
                              ▼                          ▼
                       ┌──────────────┐         ┌──────────────────┐
                       │ Local files   │         │ Bahulam Gateway  │
                       │ previews/tools│         │ model routing    │
                       └──────────────┘         └──────────────────┘

You run bahulam workspace open [path]
The CLI starts a localhost service and opens a tokenized browser URL
The browser reads the selected local root through the service
Chat turns are sent through the CLI-authenticated remote agent path
Tool calls execute locally against the granted root
Files, previews, trace events, approvals, and chat updates stream back to the browser

Glossary

Term	Definition
BM25	Best Matching 25 — text retrieval algorithm used for project indexing
BYOK	Bring Your Own Key — use your own API key instead of the platform default
BYOM	Bring Your Own Model — connect a custom model endpoint
Checkpoint	A save point recorded before auto-approved edits, enabling undo
Credit	Unit of billing on the platform default plan
Explorer	Sub-agent that reads files and searches code (read-only)
Full autopilot	Mode that skips approval prompts while hard safety blocks still apply
Gateway	Bahulam model routing layer for platform and BYOK calls
Headless	Non-interactive mode for automation and benchmarks
HITL	Human-in-the-loop — review-and-confirm workflow
Local browser workspace	Browser UI served by the CLI on `127.0.0.1` for local files, chat, previews, tool trace, uploads, and approvals
MCP	Model Context Protocol — connect external tools and data sources
Orchestrator	The main agent that coordinates sub-agents and tool calls
Planner	Sub-agent that designs architecture and implementation approach
REPL	Read-Eval-Print Loop — Bahulam’s interactive terminal interface
Resume	Continue a previous session with context preservation
Skill	A portable SKILL.md bundle with instructions and references
Sub-agent	A specialized agent (explorer, planner, etc.) that handles a specific role
Trust	Auto-approval granted for a specific tool from a specific agent in a session

Troubleshooting Sub-Agent Spawning Pattern

Reference

Environment Variables

Bahulam runtime

Local browser workspace

Model provider keys (BYOK)

Logging & debugging

Advanced / rare

Files on Disk

~/.bahulam/ (Global Config)

.bahulam/ (Project-Local)

Keyboard Shortcuts

Exit Codes

Permission Modes

Risk Tiers

Resume Modes

Event Types

Tool Catalog

File I/O

Search

Shell

Git

Web

Agent

Skills

MCP (Model Context Protocol)

Scheduling

Other

File Structure for the Bahulam NPM Package

Data Flow

Terminal CLI

Local browser workspace

Glossary

`~/.bahulam/` (Global Config)

`.bahulam/` (Project-Local)