Run Bub for the first time

Start with the Bub app, then adapt it to your work. This tutorial gives it a workspace and instructions, checks that commands work, and runs a conversation with a model.

Follow Install Bub for the application setup and choose a model in Configure Bub. The model-backed step needs the credentials for that provider. The command check works without them.

Give Bub a workspace

The workspace is the directory Bub uses for your project. Create one and run the remaining commands there:

mkdir hello-bub
cd hello-bub

Put your working instructions in AGENTS.md:

cat > AGENTS.md <<'EOF'
You are the Bub agent for this workspace.
Read files before editing them.
Keep replies short and specific.
EOF

The application reads this file when it builds the system prompt. You can change it as you learn which instructions help with your work.

Check a command

bub run ",help"

The output lists commands such as ,skill and ,tape.info. This checks the application’s command path without calling a model.

Commands begin with a comma at the start of a line. An unknown command falls back to a shell command, so use a known command for this check.

Start a conversation

With your model configured, run:

bub run "Summarize the purpose of this workspace."

Bub passes the message and workspace instructions to its agent, records the conversation, and prints the response. For an interactive conversation, use:

bub chat

If a command works but a conversation fails, check the model name and credentials in Configure Bub. If a plugin is missing, bub hooks shows which hook implementations the application discovered.

Make it your own

• Add a project skill for a procedure you want Bub to follow.
• Add an application tool when it needs to call your code.
• Write a plugin to change application behavior.