📌Overview

Purpose: Livebook Tools aims to enhance the workflow with .livemd files by providing a command-line interface (CLI) that integrates seamlessly with Livebook sessions.

Overview: Livebook Tools is a versatile CLI tool designed to empower developers working with Elixir's Livebook. It allows users to sync their .livemd files with an active Livebook session, enabling easier editing with AI-powered editors and automating code execution.

Key Features:

• BYOE (Bring Your Own Editor): Sync your .livemd files to an active Livebook session, allowing for seamless editing in AI-powered code editors like Cursor.

• MCP Server: A simple model context protocol server that connects AI coding agents to Livebook sessions, facilitating advanced coding assistance.

• Run Livebooks from the CLI: Convert and execute .livemd files as Elixir scripts from the command line, making it convenient to run Livebooks as cron jobs or in other automated settings.

---

LivebookTools

Livebook Tools is a CLI tool that enhances working with .livemd files.

Primary Features

• BYOE (Bring Your Own Editor): Sync .livemd files to an open Livebook session to edit them in AI-powered code editors like Cursor.
• MCP Server: A simple model context protocol server for connecting AI coding agents to Livebook sessions.
• Run Livebooks from the CLI: Convert .livemd files to Elixir scripts and run them top to bottom like a .exs script, useful for cron jobs.

Installation

Livebook Tools is an Elixir escript.
Install it with:

mix escript.install github thmsmlr/livebook_tools

Ensure the escript directory is on your PATH:

# for normal Elixir users
export PATH="$HOME/.mix/escripts:$PATH"

# for asdf Elixir users
for escripts_dir in $(find "${ASDF_DATA_DIR:-$HOME/.asdf}/installs/elixir" -type d -name "escripts" 2>/dev/null); do
  export PATH="$escripts_dir:$PATH"
done

Running Livebook

Livebook Tools requires connecting to a running Livebook server via distributed Elixir.
Add these environment variables to your ~/.bashrc or ~/.zshrc:

export LIVEBOOK_NODE="livebook@127.0.0.1"
export LIVEBOOK_COOKIE="secret"

Both Livebook and Livebook Tools will auto-discover these for connection.
If using Livebook Desktop, add these to ~/.livebookdesktop.sh as well.

For more information on Livebook Desktop, see the Livebook HexDocs.

Setting up MCP Server

The MCP Server implements the model context protocol, allowing AI coding agents to connect to Livebook sessions.
It is tested with Cursor (https://www.cursor.com/), but should work with any AI code editor supporting MCP.
The MCP server runs via STDIO—simply have Cursor connect via command to auto-discover the tools and connect.

For more on how MCP works with Cursor, see the Cursor MCP docs.

Useful Tips

To customize code behavior depending on whether it's running in Livebook or via CLI, use the following Elixir snippet:

# Detect if running in Livebook
is_livebook = !String.ends_with?(__ENV__.file, ".exs")

# Use empty argv list in Livebook, else get system arguments
argv = if is_livebook, do: [], else: System.argv()

# Parse command line arguments with OptionParser
{parsed_opts, positional_args, invalid_opts} =
  OptionParser.parse(
    argv,
    strict: [
      dry_run: :boolean,
      limit: :integer
    ],
    aliases: [
      d: :dry_run,
      l: :limit
    ]
  )

# Extract options with defaults
dry_run = Keyword.get(parsed_opts, :dry_run, false)
limit = Keyword.get(parsed_opts, :limit, 10)