bit-wrangler 1.0.0

Translate natural-language shell instructions into Linux commands using a local OLLAMA model.

bit - Bash Instruction Translator

bit is a Python CLI that translates natural-language shell instructions into Linux shell commands by calling a locally running OLLAMA model.

Quick Installation

pip install bit-wrangler

Example Usage

$ bit create folder new_folder
mkdir new_folder

By default, bit prints the generated command to stdout.

If you want bit to place the generated command into your current shell prompt for review, first enable the Bash or Zsh shell integration (this only has to be done once).

Activate shell integration:

# Bash
source <(bit --activate bash)    # alternatively replace bash with zsh

Option 1 (using Ctrl-x Ctrl-b):

find large log files in current directory
# press Ctrl-x Ctrl-b to replace the prompt with the generated command

Option 2 (using bit function):

bit find large log files in current directory
# the generated command is staged into the prompt for review

Features

• Translates free-form instructions into one shell command.
• Stores configuration in ~/.bit using TOML.
• Supports interactive model selection with bit --setup.
• Exposes shell integration instructions for Bash and Zsh so generated commands can be inserted into the prompt buffer.
• Builds as a standard Python package with python -m build.

Requirements

• Python 3.11 or newer.
• A local OLLAMA installation.
• An OLLAMA server available at http://127.0.0.1:11434.
• At least one installed OLLAMA model.

Installation

Build and install locally:

python -m build
python -m pip install dist/bit_wrangler-1.0.0-py3-none-any.whl

Or install in editable mode while developing:

python -m pip install -e .

After installation, the bit command is available directly on the command line.

Development Tools

Install the development dependencies:

python -m pip install -e ".[dev]"

Run the formatter:

black src tests

Run Ruff:

ruff check src tests

Run Flake8:

flake8 src tests

Run mypy:

mypy src

Initial Setup

Run:

bit --setup

This command:

1. Queries the local OLLAMA instance for installed models.
2. Displays them as a numbered list.
3. Prompts you to select one.
4. Saves the result in ~/.bit.

The config file is TOML and looks like this:

model = "llama3.1:8b"
host = "http://127.0.0.1:11434"

Usage

Translate an instruction:

bit create folder new_folder
bit find large log files in current directory
bit show disk usage for home directory

Print Bash integration helper:

bit --activate bash

Print Zsh integration helper:

bit --activate zsh

Print Bash deactivation helper:

bit --deactivate bash

Print Zsh deactivation helper:

bit --deactivate zsh

Show help:

bit --help

Shell Integration

The standalone bit executable only prints commands. If you want generated commands staged into your current shell prompt so you can review and edit them before execution, source the appropriate shell integration.

To enable that widget in Bash:

source <(bit --activate bash)

To enable that widget in Zsh:

source <(bit --activate zsh)

To unload the integration in Bash:

source <(bit --deactivate bash)

To unload the integration in Zsh:

source <(bit --deactivate zsh)

After sourcing the Zsh integration, you can also invoke bit directly as a shell function:

bit create folder new_folder

That direct Zsh function call does not execute the generated command immediately. Instead, it stages the translated shell command into the next prompt so you can review or edit it before pressing Enter.

Then type a natural-language instruction directly at the shell prompt and press Ctrl-x Ctrl-b. The widget will:

1. Read the current command line buffer as the instruction.
2. Call the installed bit CLI.
3. Replace the current command line with the generated shell command.

Nothing is executed automatically. You can edit the generated command and then press Enter yourself.

To load this automatically, add the matching source <(bit --activate ...) line to your shell startup file.

In Zsh, sourcing the integration also defines a bit shell function that shadows the installed executable in that shell session. Administrative commands such as bit --setup, bit --help, bit --activate zsh, and bit --deactivate zsh still pass through to the real CLI.

Build

Create a source distribution and wheel:

python -m build

Limitations and Security Notes

• The tool asks the model for a single shell command, but model output is still untrusted text.
• bit rejects obvious malformed multi-line and fenced responses, but it does not prove a generated command is safe.
• Review generated commands before executing them.
• Prompt staging is available through sourced shell integration rather than the standalone executable.
• The default target is Linux shell syntax even if the tool is run elsewhere.