Livebook Tools

🚀 Livebook Tools

A command-line tool that empowers you to handle .livemd files with superpowers.

Livebook Tools is a command-line utility designed to provide enhanced capabilities when working with .livemd files. Its key features include:

• BYOE (Bring Your Own Editor) - Sync your .livemd files to a running Livebook session, allowing you to edit them in an AI-enhanced code editor like Cursor.
• MCP Server - A simple Model Context Protocol server that connects AI coding agents to your Livebook session. More details are provided below.
• Run Livebooks from CLI - Convert your .livemd files into Elixir scripts and run them sequentially, just like running an .exs script. This is particularly useful if you want to turn a Livebook into a cron job.

📦 Installation

Livebook Tools is an Elixir escript. To install it, you can use the mix escript.install command:

mix escript.install github thmsmlr/livebook_tools

After installation, make sure the escript directory is in your PATH:

# For regular 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

🚀 Quick Start

For Livebook Tools to function correctly, it needs to connect to a running Livebook server using distributed Elixir. How you achieve this depends on how you run Livebook. The simplest approach is to add two environment variables to your ~/.bashrc or ~/.zshrc file:

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

When you run Livebook Tools or Livebook, both programs will read these values to ensure they can connect to each other. If you're using Livebook Desktop, you may need to add these values to the ~/.livebookdesktop.sh file. For more information on Livebook Desktop, refer to Livebook HexDocs.

💻 Usage Examples

Setting up the MCP Server

The MCP server is a simple Model Context Protocol server that allows you to connect an AI coding agent to your Livebook session. I've personally tested it with Cursor, though it should work with any AI editor supporting the MCP protocol. Here's how to configure it:

1. Install Dependencies: Ensure you have the necessary packages installed, such as elixir and erlang.
2. Start the Livebook Server: Run livebook start.
3. Set Environment Variables:

   export LIVEBOOK_SERVER_URL="http://localhost:4000"
   

4. Start the MCP Server:

   # In the Elixir REPL or a new file
   alias Livebook.Application, as: LBApp
   
   config = %{
     server_url: System.get_env("LIVEBOOK_SERVER_URL") || "http://localhost:4000",
     cookie: System.get_env("LIVEBOOK_COOKIE") || "_livebook_session"
   }
   
   {:ok, _pid} = LBApp.start_mcp_server(config)
   

💡 Usage Tip

Here are some useful tips for using Livebook Tools:

• Configure Your Editor: Enable support for .livemd files in your IDE for the best coding experience.
• Debugging: If you encounter issues, check the server logs or use iex -S mix to enter an interactive shell for debugging.
• Extend Functionality: Expand Livebook's capabilities by creating custom plugins or scripts.

We hope this information is helpful! If you have any questions, feel free to consult the documentation or reach out to the community.