Livecodes/headless Mode
Developmentlivecodes/headless-modeLivecodes/headless Mode is an Agent Skill for development published in the live-codes/livecodes repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/live-codes/livecodes/blob/HEAD/.agents/skills/livecodes/headless-mode/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/livecodes-headless-mode, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
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
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
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
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
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
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