AI agent skill · by @live-codes

Headless Mode

Run playground without visible UI using SDK methods directly. Load this skill when building Markdown compilers, code formatters, or tools that need compiled output without display.

Archived 2026-10-23 · Source updated 2026-10-11 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

This skill builds on sdk-embedding and sdk-methods. Read them first for foundational concepts.

# LiveCodes — Headless Mode

Headless mode runs LiveCodes without any visible UI. Use SDK methods to compile code, get output, and react to events.

## Setup

```javascript
import { createPlayground } from 'livecodes';

// Create headless playground - container is optional
const playground = await createPlayground({
  headless: true,
  config: {
    markup: { language: 'markdown', content: '# Hello World' },
  },
});

// Use SDK methods
const code = await playground.getCode();
console.log(code.markup.compiled); // "<h1>Hello World</h1>"
console.log(code.result); // Result page HTML
```

## Core Patterns

### Markdown compiler

```javascript
import { createPlayground } from 'livecodes';

let playground;

async function compileMarkdown(markdown) {
  if (!playground) {
    playground = await createPlayground({
      headless: true,
      config: { autoupdate: false },
    });
  }

  await playground.setConfig({
    markup: { language: 'markdown', content: markdown },
  });

  const code = await playground.getCode();
  return code.markup.compiled;
}

// Usage
const html = await compileMarkdown('# Hello\n\nWorld');
console.log(html); // "<h1>Hello</h1>\n<p>World</p>"
```

### React/JSX compiler

```javascript
import { createPlayground } from 'livecodes';

let playground;

async function compileJSX(jsxCode) {
  if (!playground) {
    playground = await createPlayground({
      headless: true,
      config: { autoupdate: false },
    });
  }

  await playground.setConfig({
    script: { language: 'react', content: jsxCode },
  });

  const code = await playground.getCode();
  return code.script.compiled;
}

const compiled = await compileJSX(`
  function App() {
    return <h1>Hello</h1>;
  }
`);
```

### Python interpreter

```javascript
import { createPlayground } from 'livecodes';

let playground;

async function runPython(code) {
  if (!playground) {
    playground = await createPlayground({
      headless: true,
      config: { autoupdate: true },
    });
  }

  // Set up console listener before running
  const outputs = [];
  playground.watch('console', ({ method, args }) => {
    outputs.push({ method, args });
  });

  await playground.setConfig({
    script: { language: 'python', content: code },
  });

  // Python runs automatically with autoupdate: true
  // Or: await playground.run();

  return outputs;
}

// Usage
const outputs = await runPython('print("Hello from Python!")');
// [{ method: 'log', args: ['Hello from Python!'] }]
```

### Get result HTML

```javascript
async function getResultHTML(config) {
  const playground = await createPlayground({
    headless: true,
    config: { ...config, autoupdate: false },
  });

  await playground.setConfig(config);

  const code = await playground.getCode();
  return code.result; // Result page HTML
}
```

### Watch for changes

```javascript
const playground = await createPlayground({
  headless: true,
  config: { autoupdate: false },
});

// Watch for compiled code changes
playground.watch('code', ({ code, config }) => {
  console.log('Compiled:', code.script.compiled);
});

// Change config - watch callback fires
await playground.setConfig({
  script: { language: 'typescript', content: 'const x: number = 1;' },
});
```

## Common Mistakes

## Headless vs Visible Mode

| Aspect    | Visible          | Headless                 |
| --------- | ---------------- | ------------------------ |
| Container | Required         | Optional                 |
| UI        | Shown            | Hidden                   |
| Use case  | User interaction | Programmatic compilation |

## When to Use Headless

- **Markdown/MDX compiler** — Get compiled HTML without display
- **Code formatter** — Use Prettier via LiveCodes
- **Language transpiler** — TypeScript → JavaScript, SCSS → CSS
- **Testing pipelines** — Run and verify code programmatically
- **Python/Ruby/Go interpreter** — Execute WASM languages and capture output