# Getting Started

AI-powered ServiceNow development agent. Describe what you want — SkyForge builds it.

***

## Prerequisites

| Tool        | Version | Install                                                                            |
| ----------- | ------- | ---------------------------------------------------------------------------------- |
| **Node.js** | 22+     | [nodejs.org/en/download](https://nodejs.org/en/download) (macOS / Linux / Windows) |

***

## Step 1 — Install

```bash
npm i -g @skyforgeai/skyforge
```

Verify:

```bash
skyforge --version
```

***

## Step 2 — Configure AI provider

Config file locations (searched in this order):

| Platform                    | Location                                              |
| --------------------------- | ----------------------------------------------------- |
| macOS / Linux (per-project) | `./skyforge.jsonc`                                    |
| macOS / Linux (global)      | `~/.config/skyforge/skyforge.jsonc`                   |
| Windows (per-project)       | `.\skyforge.jsonc`                                    |
| Windows (global)            | `C:\Users\<username>\.config\skyforge\skyforge.jsonc` |

### Anthropic (Claude)

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  },
  "model": "anthropic/claude-sonnet-4-6"
}
```

### OpenAI

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "apiKey": "sk-..."
    }
  },
  "model": "openai/gpt-4o"
}
```

### Custom / OpenAI-compatible (vLLM, LiteLLM, Ollama, company gateway)

**Step 1** — Register credentials in the TUI:

```
/connect  →  scroll to "Other"  →  enter provider ID  →  enter API key
```

**Step 2** — Add to your config file:

* macOS/Linux: `~/.config/skyforge/skyforge.jsonc`
* Windows: `C:\Users\<username>\.config\skyforge\skyforge.jsonc`

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM Gateway",
      "options": {
        "baseURL": "https://your-litellm-gateway.com/v1",
        "apiKey": "sk-your-api-key",
        "litellmProxy": true
      },
      "models": {
        "your-model-name": {
          "name": "Your Model",
          "attachment": true,
          "reasoning": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}
```

> The provider ID in `/connect` must match the key in the config (e.g. `litellm`).\
> Then run `/models` in the TUI to select your model.
>
> **Do not add a `"model"` key to the config** — model selection is done via `/models` in the TUI and saved per-session.

**Key options for LiteLLM / vLLM gateways:**

| Option                               | Where     | Description                                                                 |
| ------------------------------------ | --------- | --------------------------------------------------------------------------- |
| `litellmProxy: true`                 | `options` | **Required for LiteLLM** — fixes tool call formatting and image passthrough |
| `modalities.input: ["text","image"]` | model     | Enable image attachment support                                             |
| `attachment: true`                   | model     | Show attachment button in UI                                                |
| `reasoning: true`                    | model     | Enable thinking mode display                                                |

***

## Step 3 — Connect ServiceNow

There are three ways to connect SkyForge to your ServiceNow instance:

***

### Option A — Config file (recommended)

Add to your `skyforge.jsonc`:

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servicenow": {
      "type": "local",
      "command": ["skyforge", "mcp", "start"],
      "environment": {
        "SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
        "SERVICENOW_CLIENT_ID": "your-oauth-client-id",
        "SERVICENOW_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}
```

***

### Option B — Command palette (TUI)

Press **Ctrl+P** (or **Cmd+P** on macOS) to open the command palette, then:

```
→ Connect provider   # add AI provider credentials
→ MCP               # toggle / manage MCP connections
```

Or type `/connect` directly in the chat input to add credentials interactively.

***

### Option C — Web UI settings

When running `skyforge web`, open `http://127.0.0.1:4096` and click the **Settings** icon (⚙️):

```
Settings → Providers    # connect AI provider
Settings → MCP          # view MCP connection status
```

> Note: The web UI Settings shows connection status and lets you manage providers. Full MCP environment config (instance URL, credentials) still requires the config file.

***

### Setting up OAuth in ServiceNow

1. Go to **System OAuth → Application Registry**
2. Click **New → Create an OAuth API endpoint for external clients**
3. Fill in:
   * **Name:** `SkyForge`
   * **Redirect URL:** `http://localhost:9999/oauth/callback`
4. Submit — copy the **Client ID** and **Client Secret**
5. Add to your config above

### Basic Auth (dev instances only)

```jsonc
"environment": {
  "SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
  "SERVICENOW_USERNAME": "admin",
  "SERVICENOW_PASSWORD": "your-password"
}
```

> ⚠️ Never use basic auth in production.

***

## Step 4 — Authenticate ServiceNow

Connect your ServiceNow instance using one of these methods:

**TUI — Ctrl+P:**

```
Ctrl+P → ServiceNow Auth → choose OAuth or Basic Auth
```

**Web UI — Command Palette:**

```
Cmd+Shift+P → ServiceNow Auth → choose OAuth or Basic Auth
```

Credentials are saved and auto-loaded on every run.

* macOS/Linux: `~/.local/share/skyforge/auth.json`
* Windows: `C:\Users\<username>\.local\share\skyforge\auth.json`

> **Note:** `skyforge auth login` is for AI providers (Anthropic, OpenAI etc.), **not** for ServiceNow. Use the TUI or Web UI command palette to connect ServiceNow.

**Other auth commands:**

```bash
skyforge auth list     # show saved credentials
skyforge auth logout   # remove credentials
```

***

## Step 5 — Run

### TUI (terminal interface)

```bash
skyforge
```

### Web interface

```bash
skyforge web
```

Then open `http://127.0.0.1:4096` in your browser.

### Headless server (API only)

```bash
skyforge serve                    # default port 4096
skyforge serve --port 8080        # custom port
```

### Attach TUI to a running server

```bash
skyforge attach http://host:4096
```

Useful for CI/CD, remote servers, or connecting a local TUI to a headless instance.

### Run with a prompt directly

```bash
skyforge run "query the last 5 critical incidents"
```

***

## Example prompts

```
Query the last 5 critical incidents

Create a Business Rule on incident that sets priority to 1
when category is security and impact is 1

Create a Flow Designer flow that triggers when a P1 incident
is created, sets state to In Progress, and creates an
incident task if category is software

Create a catalog item called "New Laptop Request" on the Service
Catalog with two variables: "laptop_model" (label: "Laptop Model",
single line text, mandatory) and "justification" (label: "Business
Justification", multi-line text). Then create a Flow Designer flow
that triggers when the catalog request is submitted — it should send
an approval to the requester's manager, and if approved, create an
incident with short description "Laptop approved for [requester name]"

Deploy my changes to a new Update Set called "Sprint 24 Changes"
```

***

## Keyboard shortcuts (TUI)

SkyForge uses a **leader key** pattern. The leader is `Ctrl+X` — press and **release** it first, then press the second key. Do not hold them together (same pattern as Emacs).

| Key                                               | Action                                           |
| ------------------------------------------------- | ------------------------------------------------ |
| Press `Ctrl+X`, release, then press `A`           | Open agent picker                                |
| `Shift+Tab`                                       | Cycle to next agent                              |
| `Ctrl+Shift+Tab`                                  | Cycle to previous agent                          |
| `Escape`                                          | Interrupt current agent / stop running operation |
| Press `Ctrl+X`, release, then press `Up Arrow`    | Go to parent session (from subagent)             |
| Press `Ctrl+X`, release, then press `Right Arrow` | Next child session                               |
| Press `Ctrl+X`, release, then press `Left Arrow`  | Previous child session                           |
| `Ctrl+P`                                          | Command palette                                  |
| `/connect`                                        | Add AI provider credentials                      |
| `/models`                                         | Switch model                                     |
| `/themes`                                         | Change theme                                     |
| `Ctrl+C`                                          | Exit SkyForge                                    |

> **macOS tip:** `Ctrl+X` combos are two separate keypresses — press and release `Ctrl+X`, then press the next key.

***

## Agents

| Agent       | Shift+Tab    | Description                                                                                                                                 |
| ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Build**   | ✅            | Default — full tool access, creates and deploys ServiceNow artifacts                                                                        |
| **Plan**    | ✅            | Read-only — analysis and exploration, denies all edits                                                                                      |
| **Review**  | ✅            | ServiceNow code review — quality, security, widget coherence, DRY analysis. Writes report to `.skyforge/reviews/`, then hands back to Build |
| **General** | ❌ `@general` | Multi-step subagent for complex parallel tasks                                                                                              |

Switch between Build / Plan / Review with **Shift+Tab**.\
Invoke General with `@general` in the chat input. Custom agents can be configured in `skyforge.jsonc`:

```jsonc
{
  "agent": {
    "sn-reviewer": {
      "model": "anthropic/claude-sonnet-4-6",
      "description": "ServiceNow code reviewer — trigger with @sn-reviewer",
      "mode": "subagent",
      "prompt": "You are a ServiceNow code reviewer. Check for best practices, security, and performance issues. Never make changes — analysis only.",
      "temperature": 0.1,
      "steps": 20,
      "color": "#FF8C00",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "sn-deployer": {
      "model": "anthropic/claude-sonnet-4-6",
      "description": "ServiceNow deployment agent — handles update sets and promotions",
      "mode": "subagent",
      "prompt": "You are a ServiceNow deployment specialist. Focus on update set management, environment promotion, and deployment validation.",
      "steps": 30
    }
  }
}
```

**Agent config options:**

| Option        | Description                                                                               |
| ------------- | ----------------------------------------------------------------------------------------- |
| `model`       | Override model for this agent                                                             |
| `prompt`      | Custom system prompt                                                                      |
| `description` | Shown in `@agent` autocomplete                                                            |
| `mode`        | `subagent` (invoke with `@name`), `primary` (appears in Shift+Tab rotation), `all` (both) |
| `temperature` | 0.0–1.0, lower = more deterministic                                                       |
| `steps`       | Max agentic iterations                                                                    |
| `color`       | Hex color in UI (e.g. `#FF5733`)                                                          |
| `permission`  | `edit`, `bash`, `web_fetch` → `allow` or `deny`                                           |
| `hidden`      | Hide from `@` autocomplete (subagent only)                                                |

Invoke subagents with `@agent-name` in the chat input.

***

## Extend with MCP & Plugins

### Additional MCP servers

Connect any MCP-compatible server alongside the built-in ServiceNow MCP:

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servicenow": {
      "type": "local",
      "command": ["skyforge", "mcp", "start"],
      "environment": {
        "SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com"
      }
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    },
    "custom-tools": {
      "type": "local",
      "command": ["node", "./my-mcp-server.js"]
    }
  }
}
```

### Plugins

Extend SkyForge with npm packages or local plugins that add tools, auth providers, and event hooks:

```jsonc
{
  "plugin": ["my-skyforge-plugin", "file://./local-plugin"]
}
```

***

## Finding tools

SkyForge has 393 tools, lazy-loaded. Search for what you need:

```
search for catalog item tools
search for flow designer tools
search for CMDB tools
```

***

## Logs

| Log                        | macOS / Linux                                             | Windows                                                 |
| -------------------------- | --------------------------------------------------------- | ------------------------------------------------------- |
| Session (local/dev build)  | `~/.local/share/skyforge/log/dev.log`                     | `C:\Users\<username>\.local\share\skyforge\log\dev.log` |
| Session (installed binary) | `~/.local/share/skyforge/log/` (timestamped `.log` files) | `C:\Users\<username>\.local\share\skyforge\log\`        |
| MCP calls                  | `~/.skyforge/skyforge-mcp.log`                            | `C:\Users\<username>\.skyforge\skyforge-mcp.log`        |
| MCP metrics                | `~/.skyforge/skyforge-metrics.log`                        | `C:\Users\<username>\.skyforge\skyforge-metrics.log`    |

**macOS / Linux:**

```bash
# Tail active log (dev/local build)
tail -f ~/.local/share/skyforge/log/dev.log

# Tail latest session log (installed binary)
ls -t ~/.local/share/skyforge/log/*.log | head -1 | xargs tail -f

# Watch MCP tool calls
tail -f ~/.skyforge/skyforge-mcp.log

# Run with full DEBUG output
skyforge --log-level DEBUG --print-logs
```

**Windows (PowerShell):**

```powershell
# Tail active log (dev build)
Get-Content "$env:USERPROFILE\.local\share\skyforge\log\dev.log" -Wait -Tail 20

# Tail latest session log
Get-ChildItem "$env:USERPROFILE\.local\share\skyforge\log\*.log" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Wait -Tail 20

# Watch MCP tool calls
Get-Content "$env:USERPROFILE\.skyforge\skyforge-mcp.log" -Wait -Tail 20

# Run with full DEBUG output
skyforge --log-level DEBUG --print-logs
```

***

## Troubleshooting

**Reset SkyForge to a clean state**

If something is badly broken or you want to start fresh, wipe all config, data, and cache:

**macOS / Linux:**

```bash
rm -rf ~/.config/skyforge      # config
rm -rf ~/.local/share/skyforge # sessions, logs, data
rm -rf ~/.local/share/opentui  # TUI state
rm -rf ~/.cache/skyforge       # cache
rm -rf ~/.skyforge             # project files
```

**Windows (PowerShell):**

```powershell
Remove-Item -Recurse -Force "$env:USERPROFILE\.config\skyforge"      # config
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\share\skyforge" # sessions, logs, data
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\skyforge"       # cache
Remove-Item -Recurse -Force "$env:USERPROFILE\.skyforge"             # project files
```

Then reinstall and run:

```bash
npm i -g @skyforgeai/skyforge@latest
skyforge
```

**"Authentication failed" / 401 errors**

* No trailing slash on `SERVICENOW_INSTANCE_URL`
* Verify Client ID and Secret are correct
* Check OAuth app is **Active** in ServiceNow
* Try basic auth first to confirm connectivity

**"Tool not found"**

* Tools are lazy-loaded — type `search for X tools` first

**MCP not connecting**

```bash
tail -f ~/.skyforge/skyforge-mcp.log
SN_MCP_DEBUG=true skyforge
```

**Web UI file attach not working**

* Must be on `localhost` or HTTPS for file picker to work
* Drag and drop works on all contexts

***

## Support

Have a bug or feature request? Submit it at [**GitHub Issues**](https://github.com/tryskyforge/skyforgeissues).

## License

SkyForge is licensed under the [Elastic License 2.0](https://skyforgeai.gitbook.io/docs/license). Free for personal and internal use. Commercial redistribution requires a license.