Serac Documentation

# Global installation (recommended)
npm install -g @serac-labs/serac

# Verify installation
serac --version

# Start the TUI (auto-initializes on first run)
serac

# This automatically creates:
# - .mcp.json (MCP server configuration)
# - CLAUDE.md (AI agent instructions)
# - .env (environment configuration)

# In the TUI, type /auth to authenticate
/auth

# This configures:
# - LLM provider (Claude, GPT, Gemini, Ollama)
# - ServiceNow OAuth credentials
# - Enterprise features (optional)

# Just type your request in natural language:
"Create a widget showing high-priority incidents"

"Show me all incidents from last week"

"Create a business rule for auto-assignment"

~/.local/share/serac/auth.json

# ServiceNow credentials
SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET=your-client-secret

# Optional: Pre-configured refresh token
SERVICENOW_REFRESH_TOKEN=your-refresh-token

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.3

# Configure Serac
DEFAULT_LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
DEFAULT_OLLAMA_MODEL=llama3.3

# Reference a file
How is auth handled in @src/auth/handler.ts?

# Run a shell command
!git status

# Both outputs are added to the conversation

# Add to ~/.bashrc or ~/.zshrc
export EDITOR="code --wait"   # VS Code
export EDITOR="cursor --wait" # Cursor
export EDITOR="vim"           # Vim
export EDITOR="nano"          # Nano

{
  "$schema": "https://serac.build/config.json",
  "keybinds": {
    "leader": "ctrl+x",
    "app_help": "<leader>h",
    "session_compact": "none",
    "input_submit": "ctrl+enter"
  }
}

{
  "$schema": "https://serac.build/config.json",

  // Model configuration
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-3-5-haiku-20241022",

  // UI settings
  "theme": "serac",
  "autoupdate": true,

  // Tool restrictions
  "tools": {
    "write": false,    // Disable write tool
    "bash": false      // Disable bash tool
  },

  // Permission modes: "allow", "ask", "deny"
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },

  // Sharing: "manual", "auto", "disabled"
  "share": "manual",

  // Instructions from files
  "instructions": ["CONTRIBUTING.md", "docs/*.md"],

  // Disable specific providers
  "disabled_providers": ["openai", "gemini"],

  // Provider configuration
  "provider": {},

  // Custom agents, commands, keybinds
  "agent": {},
  "command": {},
  "keybinds": {},

  // MCP servers
  "mcp": {}
}

{
  "model": "{env:SNOW_FLOW_MODEL}",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,  // Read-only agent
        "edit": false
      }
    }
  }
}

---
description: Reviews code for best practices
model: anthropic/claude-sonnet-4-20250514
tools:
  write: false
  edit: false
---

You are a code reviewer. Focus on security, performance, and maintainability.

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report.
Focus on failing tests and suggest fixes.

{
  "$schema": "https://serac.build/config.json",
  "permission": {
    "edit": "ask",       // Prompt before editing
    "bash": "ask",       // Prompt before bash commands
    "webfetch": "deny"   // Disable web fetching
  }
}

{
  "permission": {
    "bash": {
      "git push": "ask",
      "git status": "allow",
      "terraform *": "deny",
      "*": "ask"
    }
  }
}

# My Project Rules

## Project Structure
- `packages/` - Workspace packages
- `infra/` - Infrastructure definitions

## Code Standards
- Use TypeScript with strict mode
- Shared code goes in `packages/core/`
- Follow ESLint and Prettier configs

{
  "instructions": ["CONTRIBUTING.md", "docs/*.md", ".cursor/rules/*.md"]
}

// .serac/plugin/example.js
export const MyPlugin = async ({ project, client, $, directory }) => {
  console.log("Plugin initialized!")

  return {
    // Hook into events
    event: async ({ event }) => {
      if (event.type === "session.idle") {
        // Session completed
      }
    },

    // Intercept tool execution
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    }
  }
}

serac github install

serac serve --port 4096 --hostname 127.0.0.1

# Create a widget
"Create a dashboard widget for incident metrics"

# Automate a process
"Create business rule to auto-assign incidents by category"

# Query and analyze
"Analyze incident trends from the past month"

# Complex task with multiple agents
"Build a complete workspace for IT support"

{
  "mcp": {
    "servicenow-unified": {
      "type": "local",
      "command": ["node", "dist/mcp/servicenow-mcp-unified/index.js"],
      "environment": {
        "SERVICENOW_INSTANCE_URL": "{{SNOW_INSTANCE}}",
        "SERVICENOW_CLIENT_ID": "{{SNOW_CLIENT_ID}}",
        "SERVICENOW_CLIENT_SECRET": "{{SNOW_CLIENT_SECRET}}"
      },
      "enabled": true
    }
  }
}

# macOS config location
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows config location
%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "servicenow-unified": {
      "command": "node",
      "args": ["/path/to/serac/dist/mcp/servicenow-mcp-unified/index.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_CLIENT_ID": "your-client-id",
        "SERVICENOW_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

# After starting serac once, copy config to Cursor
cp .mcp.json .cursor/mcp.json

# Or create .cursor directory first
mkdir -p .cursor && cp .mcp.json .cursor/mcp.json

# After starting serac once, copy config to Windsurf
cp .mcp.json mcp_config.json

# Continue.dev config location
~/.continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "node",
          "args": ["/path/to/serac/dist/mcp/servicenow-mcp-unified/index.js"]
        }
      }
    ]
  }
}

# Global npm installation
npm root -g
# Output: /usr/local/lib/node_modules
# Full path: /usr/local/lib/node_modules/@serac-labs/serac/dist/mcp/...

# Or use which to find the binary
which serac

// ALL OF THESE BREAK SERVICENOW:
const x = 5;                    // SyntaxError
let items = [];                 // SyntaxError
const fn = () => {};            // SyntaxError
var msg = `Hello ${name}`;      // SyntaxError
for (let item of items) {}    // SyntaxError
var {name, id} = user;          // SyntaxError
array.map(x => x.id);           // SyntaxError
class MyClass {}                // SyntaxError

// THESE WORK IN SERVICENOW:
var x = 5;
var items = [];
function fn() { return 'result'; }
var msg = 'Hello ' + name;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
}
var name = user.name;
var id = user.id;

// 1. Create Update Set FIRST
snow_update_set_manage({
  action: 'create',
  name: "Feature: Incident Dashboard",
  description: "Widget showing incident metrics"
});

// 2. Develop (changes auto-tracked)
snow_create_artifact({...});
snow_create_business_rule({...});

// 3. Complete Update Set
snow_update_set_manage({
  action: 'complete',
  update_set_id: 'sys_id_here'
});

// SERVER SCRIPT - Initialize data
data.message = "Hello";
data.items = [];
if (input.action === 'loadItems') {
  data.items = getItems();
}

// CLIENT SCRIPT - Handle UI interactions
c.loadItems = function() {
  c.server.get({action: 'loadItems'}).then(function() {
    console.log(c.data.items);
  });
};

// HTML TEMPLATE - Display data
<button ng-click="loadItems()">Load</button>
<div ng-repeat="item in data.items">{{item}}</div>

# In the TUI, authenticate with enterprise features
/auth

# Connect Jira
# (Follow prompts to authorize)

# Then in the TUI, complete a Jira story:
"Complete JIRA-1234"