Getting Started

Getting Started

Install

Install Bahulam globally via npm:

npm i -g @bahulam/code

You can also install a specific version:

npm i -g @bahulam/code@latest

Or run without installing using npx:

npx @bahulam/code@latest

Sign In

Run Bahulam in any project directory:

bahulam

On first launch, Bahulam opens a browser window and redirects you to bahulam.ai to authenticate. If you’re in a headless environment, it will print a URL you can open manually.

→ Opening browser for authentication...
→ If the browser didn't open, visit:
  https://bahulam.ai/auth/cli?code=...

You can also sign in explicitly at any time:

bahulam login

Once authenticated, your session is cached locally and you won’t need to sign in again on that machine.

Your First Turn

After signing in, you’ll see the Bahulam REPL prompt:

> _

Try a simple task:

> what does this project do?

Bahulam will:

  1. Explore the project structure
  2. Read key configuration files
  3. Summarize what it found

For a code change, try:

> add a .gitignore file

Bahulam plans the change, shows you a diff, applies it, and reports the result.

Local Browser Workspace

For a Cloud IDE-style browser UI over local files, run:

bahulam workspace open .

This starts a localhost-only service on your machine and opens a browser with a file tree, tabs, previews, chat, trace, uploads, and approvals. The agent still uses your CLI authentication, while file reads, edits, previews, and document conversion happen against the local folder you granted.

Open a document folder or a specific file the same way:

bahulam workspace open ~/Documents/reports
bahulam workspace open ~/Documents/report.docx --port 8787

See Local Browser Workspace for session resume, supported viewers, Office conversion, and troubleshooting.

The .bahulam/ Folder

Run bahulam init in a project to scaffold the project-local .bahulam/ folder:

bahulam init

The project memory file is .bahulam/BAHULAM.md. Use it for durable project facts that Bahulam should read on every turn, such as the stack, test command, lint command, key directories, code style, and critical rules.

bahulam init creates these hand-editable files:

PathPurpose
.bahulam/BAHULAM.mdBahulam project memory loaded into context
.bahulam/settings.jsonProject settings, environment entries, permissions, and hook configuration
.bahulam/config.jsonProject policy for context loading, planning, tasks, HITL, and command defaults
.bahulam/project.mdAdditional durable project notes
.bahulam/style.mdCode style and communication conventions
.bahulam/hitl.mdProject-specific human approval guidance
.bahulam/tasks/Markdown task board files: backlog.md, active.md, blocked.md, and done.md
.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/trust.jsonProject trust rules for approvals

Bahulam may also write runtime files such as .bahulam/approvals.log, .bahulam/sessions/, and .bahulam/reports/. The scaffolded .bahulam/.gitignore keeps local-only runtime files out of source control.

Resuming a Session

Continue where you left off:

# Resume the most recent session
bahulam --resume
 
# Resume a specific session
bahulam --resume session_abc123

Bahulam automatically selects the best context strategy (full transcript, summary, or summary + recent messages) based on the model’s context window.

Next Steps

WelcomeOverview