Gimble.dev

Gimble is a cross-platform command-line tool for robotics debugging and observability on macOS and Linux.

This README is reorganized for a concise quick start. For an expanded reference (commands, env, examples) and troubleshooting, see the docs/ folder.

Quick start

1. Install (recommended — installs latest release):

curl -fsSL https://raw.githubusercontent.com/Saketspradhan/Gimble-dev/main/scripts/install_latest.sh | bash

2. Verify installation:

gimble --version

3. First run (initializes local config via interactive wizard):

gimble

Local config/secrets are stored under:

• macOS: ~/Library/Application Support/gimble/
• Linux: ~/.config/gimble/

Package manager installs

• macOS (Homebrew):

brew tap saketspradhan/gimble https://github.com/Saketspradhan/Gimble-dev
brew install gimble

• Linux (APT): one-time repository setup, then install:

curl -fsSL https://raw.githubusercontent.com/Saketspradhan/Gimble-dev/gh-pages/gimble-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/gimble-archive-keyring.gpg >/dev/null

echo "deb [signed-by=/usr/share/keyrings/gimble-archive-keyring.gpg] https://saketspradhan.github.io/Gimble-dev stable main" \
  | sudo tee /etc/apt/sources.list.d/gimble.list >/dev/null

sudo apt update
sudo apt install gimble

Common commands

Outside a Gimble session:

• gimble or gimble session — start Gimble shell session
• gimble setup — run first-time setup wizard
• gimble keys — update OpenAI/Groq API keys (syncs to cloud for your user)
• gimble show profile — show profile details
• gimble profile <command> — manage profiles

Inside a Gimble session:

• gim chat — start Gimble Cloud session + uploader
• gim disconnect — stop cloud uploader (stay in session)
• gim keys — update API keys
• gim show profile — show active profile
• gim exit — stop uploader (fail-safe) and exit session

Profile helper commands:

• gimble profile init --name <name> --email <email> --github <github> [--provider github|gitlab] [--profile <name>]
• gimble profile set --profile <name> [--name <name>] [--email <email>] [--github <github>] [--provider github|gitlab]
• gimble profile list
• gimble profile show [profile]
• gimble profile use <profile>
• gimble profile delete <profile>

Chat models (UI)

Default provider/model:

• Groq: openai/gpt-oss-120b

Other available models shown in the UI:

• Groq: openai/gpt-oss-120b, openai/gpt-oss-20b, openai/gpt-oss-safeguard-20b, qwen/qwen3-32b, llama-3.1-8b-instant, llama-3.3-70b-versatile
• OpenAI: gpt-4o-mini, gpt-4.1-mini, gpt-4.1-nano
• GPT-Q 4K is experimental (non-selectable)

Cloud mode (private Gimble Cloud backend)

Chat and context compilation run in the cloud. The CLI stores these values in a local chat.env file:

In the cloud, gim chat will:

• create a cloud session (/v1/sessions)
• print a session URL like https://chat.gimble.dev/<username>/<session_id>
• start a background uploader which sends sanitized session logs to /v1/events:ingest

Private backend scaffold (local reference):

• /Users/<username>/Desktop/gimble-cloud

What happens in the cloud (high level)

Gimble Cloud (proprietary) handles ingestion, normalization, indexing and retrieval. High-level pipeline:

• Ingest: sanitized session logs → /v1/events:ingest
• Normalize + Store: Postgres (with Redis caching)
• Indexing: pgvector (semantic) and Meilisearch (keyword)
• Workers: produce summaries and anomaly signals
• Context compiler: builds compact prompts from recent events, summaries and vector/keyword matches
• LLM: Groq (gpt-oss-120b) answers using structured context

This keeps the client lightweight while the cloud performs scalable ingestion and retrieval.

Development and releases

Build from source:

make build

Release artifacts:

make build-linux
make build-macos

Updating/Installing latest release (same as quick start install):

curl -fsSL https://raw.githubusercontent.com/Saketspradhan/Gimble-dev/main/scripts/install_latest.sh | bash

Maintainer automation:

On each v* tag push, a GitHub Actions workflow updates Formula/gimble.rb to the new tag + tarball SHA256.

• workflow: .github/workflows/update-homebrew-formula.yml
• helper script: scripts/update-homebrew-formula.sh

Remove Gimble completely

brew uninstall --zap --force gimble || true
brew untap saketspradhan/gimble || true
sudo rm -f /opt/homebrew/bin/gimble
sudo rm -rf /opt/homebrew/share/gimble
rm -rf "$HOME/Library/Application Support/gimble" "$HOME/.config/gimble" "$HOME/.cache/gimble" "$HOME/.local/share/gimble" "$HOME/.gimble"

Reinstall (fresh)

Follow the Quick start install and verify steps above.

License

See LICENSE.