Jiva

Jiva is an autonomous AI agent for the terminal and cloud. It works with any OpenAI-compatible model provider and supports two execution modes — a general-purpose two-agent system (Manager + Worker) for complex tasks, and a code-optimized single-loop engine with LSP integration for software engineering.

Demo

---

Installation

npm install -g jiva-core
jiva setup

The setup wizard opens with a provider selection menu. Choose your provider and Jiva auto-fills the endpoint, model name, and tool format — you only supply your API key. Supported providers: Krutrim, Groq, Sarvam, OpenAI, and any OpenAI-compatible endpoint.

Development install

git clone https://github.com/KarmaloopAI/Jiva.git
cd Jiva
npm install && npm run build && npm link
jiva setup

---

Quick Start

# General-purpose interactive session
jiva chat

# Code mode — optimized for software engineering tasks
jiva chat --code

# Code mode with plan-then-approve flow
jiva chat --code --plan

# Single prompt
jiva run "What changed in the last 5 commits?"

# Single prompt in code mode
jiva run "Add error handling to the database module" --code

REPL commands

Command	Description
/help	Show available commands
/tools	List active tools
/servers	Show MCP server status
/save	Save current conversation
/load	Resume a saved conversation
/list	Browse all saved conversations
/reset	Clear conversation history
/<skill-name>	Load a skill (e.g. /graphify)
/exit	Exit Jiva

---

Execution Modes

General mode (default)

A two-agent pipeline designed for complex, multi-step tasks:

User Request
    ↓
Manager Agent    — plans, decomposes, and synthesizes
    ↓
Worker Agent     — executes subtasks with MCP tools
    ↓
Response

The Worker has access to any configured MCP server (filesystem, browser automation, shell commands, etc.). The Manager synthesizes results from all subtasks into a final coherent response. Simple conversational messages are answered directly without executing subtasks.

Code mode (--code)

A single streaming loop optimized for coding tasks:

User Request
    ↓
CodeAgent
    loop until done:
        LLM call with tool definitions
        ↓
        Tool execution (in-process, no subprocess)
        ↓
        LSP feedback after file edits
    ↓
Response

Code mode reduces latency by eliminating inter-agent overhead and running all file tools directly in the Node.js process. It includes a multi-strategy edit engine that reliably handles indentation drift and whitespace inconsistencies.

Available tools in code mode:

Tool	Description
read_file	Read files with line numbers, list directories
edit_file	Multi-strategy string replacement (9 strategies)
write_file	Create or overwrite files
glob	Find files by pattern
grep	Regex content search
bash	Run shell commands
spawn_code_agent	Delegate a sub-task to a child agent

MCP servers in code mode: Code mode does not load all MCP servers by default (too many tools bloat the context). You opt in explicitly:

# Per-invocation: pass server names via --mcp (comma-separated)
jiva chat --code --mcp browser
jiva chat --code --mcp browser,postgres

# Persistent: set codeMode:true on any server in your config
jiva config
# or edit ~/.config/jiva/config.json:
# "mcpServers": { "browser": { "command": "...", "codeMode": true } }

When MCP servers are active in code mode, their tool names (e.g. browser__screenshot) are listed in the startup banner and the agent's system prompt.

LSP integration: After each file edit, Jiva notifies the appropriate language server and appends any compiler errors to the tool result. Language servers are auto-detected from your PATH. If none is installed for a given language, the tool continues silently.

# Install language servers (optional but recommended for code mode)
npm install -g typescript-language-server typescript   # TypeScript / JavaScript
pip install python-lsp-server                          # Python
go install golang.org/x/tools/gopls@latest             # Go
rustup component add rust-analyzer                     # Rust

For a complete technical reference see Code Mode Architecture.

---

Configuration

# Run setup wizard
jiva setup

# View or update settings interactively
jiva config

# View current configuration and file path
jiva config --show

Configuration is stored at ~/.config/jiva-nodejs/config.json (Linux/macOS) or %APPDATA%\jiva-nodejs\config.json (Windows).

Provider examples

Krutrim (gpt-oss-120b)

{
  "models": {
    "reasoning": {
      "endpoint": "https://cloud.olakrutrim.com/v1/chat/completions",
      "apiKey": "kr-...",
      "model": "gpt-oss-120b",
      "type": "reasoning",
      "useHarmonyFormat": true,
      "reasoningEffortStrategy": "system_prompt"
    }
  }
}

Groq

{
  "models": {
    "reasoning": {
      "endpoint": "https://api.groq.com/openai/v1/chat/completions",
      "apiKey": "gsk_...",
      "model": "openai/gpt-oss-120b",
      "type": "reasoning",
      "reasoningEffortStrategy": "api_param"
    }
  }
}

Sarvam (sarvam-105b) — fully supported reasoning model with internal chain-of-thought. Jiva handles Sarvam's XML-format tool calls transparently and recovers automatically when large file writes hit the token limit.

{
  "models": {
    "reasoning": {
      "endpoint": "https://api.sarvam.ai/v1/chat/completions",
      "apiKey": "your-sarvam-key",
      "model": "sarvam-105b",
      "type": "reasoning",
      "reasoningEffortStrategy": "api_param",
      "defaultMaxTokens": 8192
    }
  }
}

Ollama (local)

{
  "models": {
    "reasoning": {
      "endpoint": "http://localhost:11434/v1/chat/completions",
      "apiKey": "not-needed",
      "model": "llama3.1",
      "type": "reasoning"
    }
  }
}

Any other OpenAI-compatible endpoint works the same way — set endpoint, apiKey, and model; Jiva handles the rest.

Code mode configuration

{
  "codeMode": {
    "enabled": true,
    "lsp": { "enabled": true },
    "maxIterations": 50
  }
}

Full configuration reference: Configuration Guide

---

Directive Files

Create a jiva-directive.md in your project root to orient the agent to your codebase:

# Purpose
Code review assistant for a Django web application.

# Tasks
- Scan for security vulnerabilities (SQLi, XSS, CSRF)
- Identify performance bottlenecks
- Suggest modern Python best practices

# Constraints
- Only analyze .py files
- Do not modify files without explicit approval

# Context
PostgreSQL backend, GDPR-sensitive user data.

Jiva searches for directive files automatically, in this order:

1. Path given via --directive
2. jiva-directive.md in the workspace root
3. CLAUDE.md in the workspace root
4. AGENTS.md in the workspace root
5. .jiva/directive.md in the workspace root

---

MCP Servers (general mode)

General mode uses MCP servers to extend the agent's capabilities. Jiva ships with the filesystem server enabled; additional servers can be added via jiva config.

Recommended servers

Playwright — browser automation, web scraping, screenshot capture

jiva config
# MCP Servers > Add Server
# Name: playwright  Command: npx  Args: @playwright/mcp@latest

Desktop Commander — shell command execution, process management

# Name: desktop-commander  Command: npx  Args: -y desktop-commander

Other popular servers: GitHub, Postgres, Slack, Google Maps — see modelcontextprotocol/servers.

---

Cloud Deployment

Jiva can be deployed as a stateless, auto-scaling HTTP/WebSocket service on Google Cloud Run with GCS-backed session persistence and multi-tenant isolation.

git clone https://github.com/KarmaloopAI/Jiva.git
cd Jiva
./deploy.sh YOUR_PROJECT_ID us-central1

The deployment script enables required GCP APIs, creates the GCS bucket, configures IAM roles, and deploys the container. After deployment:

SERVICE_URL=$(gcloud run services describe jiva --region=us-central1 --format='value(status.url)')

# Health check
curl $SERVICE_URL/health

# Chat via REST
curl -X POST $SERVICE_URL/api/chat \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: my-session" \
  -d '{"message": "Hello, Jiva!"}'

Code mode in the cloud:

gcloud run services update jiva \
  --set-env-vars JIVA_CODE_MODE=true \
  --region us-central1

Full guide: Cloud Run Deployment

---

Skills

Skills are reusable workflow modules defined by a SKILL.md file. They work standalone (no persona needed) and in both chat and code mode.

Standalone skills — drop a skill into ~/.claude/skills/<name>/SKILL.md (Claude-compatible format) and Jiva discovers it automatically at startup. The skill's metadata appears in the agent's system prompt so it can be invoked by description.

Slash commands — invoke any skill from the REPL:

/graphify
> visualise the dependency graph for this repo

Jiva loads the skill's instructions and prepends them to your message before sending it to the agent.

Persona-based skills — for teams, skills can be grouped into personas that bundle MCP servers, directives, and model behavior:

jiva persona list
jiva persona activate data-analyst
jiva persona create-skill my-skill --description "Custom capability" --author "Your Name"

Skills bundle MCP servers, directives, and model behavior overrides into portable .skill files. See Personas Guide.

---

Programmatic Usage

import { DualAgent, CodeAgent, createModelClient, ModelOrchestrator,
         MCPServerManager, WorkspaceManager, ConversationManager,
         createStorageProvider } from 'jiva-core';

const reasoningModel = createModelClient({
  endpoint: 'https://api.groq.com/openai/v1/chat/completions',
  apiKey: process.env.API_KEY!,
  model: 'openai/gpt-oss-120b',
  type: 'reasoning',
  reasoningEffortStrategy: 'api_param',
});
const orchestrator = new ModelOrchestrator({ reasoningModel });
const storageProvider = await createStorageProvider();
const workspace = new WorkspaceManager(storageProvider);
await workspace.initialize();
const conversationManager = new ConversationManager(storageProvider);

// General mode
const mcpManager = new MCPServerManager();
await mcpManager.initialize({
  filesystem: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()], enabled: true },
});
const agent = new DualAgent({ orchestrator, mcpManager, workspace, conversationManager });
const response = await agent.chat('What files are in this directory?');
console.log(response.content);
await agent.cleanup();

// Code mode
const codeAgent = new CodeAgent({ orchestrator, workspace, conversationManager, maxIterations: 50, lspEnabled: true });
const codeResponse = await codeAgent.chat('Refactor the auth module to use async/await');
console.log(codeResponse.content);
await codeAgent.cleanup();

Both DualAgent and CodeAgent implement the IAgent interface and are interchangeable in application code.

---

Development

npm run build        # compile TypeScript
npm run dev          # watch mode
npm run type-check   # type-check without emit

---

Documentation

Document	Description
Quick Start	Get running in 30 seconds
Configuration Guide	All config options and provider examples
Code Mode Architecture	How code mode works internally
Cloud Run Deployment	Production deployment guide
Personas Guide	Skills and persona system
Troubleshooting	Common issues and fixes
Release Notes	Version history

---

Contributing

Contributions are welcome. Please ensure new features include error handling and that documentation is updated. Open a PR against the develop branch.

License

MIT

References

• gpt-oss-120b Model Card
• Harmony Response Format
• Model Context Protocol
• Krutrim Cloud API
• Sarvam AI API