Sharkbait

Experimental: This project is under active development. APIs may change, features may break, and Dory might forget what she was doing. Use at your own risk!

"Just keep coding, just keep coding..." — Dory, probably

Sharkbait is a CLI-based AI coding assistant built with Bun and TypeScript. It uses the OpenAI Responses API (not Chat Completions) for enhanced tool calling and streaming. Like Nemo escaping the dentist's fish tank, it helps you break free from tedious coding tasks.

The development environment is powered by Anthropic skills and Claude Code plugins that provide specialized workflows across design, engineering, research, and operations.

The ASCII Shark

                              +.+++.
                            ## ....-### -
                           +  ###++++-#++-
                           - ##+-++--+-+--.
                             #++++-+-------..
                           - -#+-----++-.....
                           ##-.----+-.  ###########
                           #..-++--. +#####+.   .. .
                       ####..--+--..##. ...-+####++-.
                     #  . .-.--+-. ## .+++++++++++-++..
                    # ##+### -+--.## .--+++++++++++++-+
                   + .#+-###.--+.-# -+--------+++++-...
                     -#.-###.--- #+.+---... ...-+++-.###
                  ###.--+##-.++.## ---...####...-+++- .###
    #           .. ##- --## -#.-#.-+...##   ###.-++++   ##+
   #- ###+--+#---#- # +++-..#-.+# +-.-##.    ##-.-+++#####.
  ## ##---+##+--++#+.+-+-+--+-.+#.+-.####--.###+.-+++.###+.
  # .#+++----++-+-++.#..+-.---.#+---..########..-++++-....-+##-.
  #. #++##++--+----+--#.#-----.#+-----........-+++++++++++-----+#.
  #- #++-+++++++--+++.# -#..--.+#.--------....--+++++--.--.#++++#+
  +# ##---+++++++---+.+#.-#+---.#+..-------++--.....--++-.++--++#.
   # .##+++--++-++-+-....++- ....+#...----++--++####++..-##++++##
    #  ###+++-++-++..  .    +##..+.+#-......------....+#+++++##-
     #   #####+++.           ## ++--+.  ..      .-###########-
       #.    .+.                ..- +.               .###-
           #-.                +   #

Features

• Fast — Built on Bun. Swims through code faster than Marlin crossing the EAC
• Responses API — Uses OpenAI's Responses API for better streaming and tool calling
• Tool-equipped — File ops, shell commands, Git, GitHub. Everything but the Ring of Fire
• Persistent Memory — Beads give your AI long-term memory that survives sessions (unlike Dory)
• Git-backed Context — Your AI's memory lives in your repo. Clone it, branch it, merge it
• Beautiful UI — Ink-based terminal interface. P. Sherman would approve
• Safe — Confirms dangerous operations before executing. No surprise rm -rf moments

The Memory Problem

Most AI coding assistants have the memory of... well, Dory. They forget context between sessions, lose track of what you were working on, and make you repeat yourself constantly.

Sharkbait is different. Built-in Beads provide persistent, git-backed memory that survives across sessions:

• Task Memory: Create a bead for a feature, and Sharkbait remembers the context, decisions, and progress — even after you close the terminal
• Git-Native: Beads are stored alongside your code in git, so your AI's memory travels with your repo
• No External Services: Your context stays local. No cloud sync, no API calls for memory — just git

Skills & Plugins

Sharkbait's development environment ships with the full Anthropic Skills catalog and a curated set of Claude Code plugins. These are used during development with Claude Code — they are not runtime features of the Sharkbait application itself.

Installed Anthropic Skills

| Category | Skills | What They Do | |----------|--------|--------------| | Design | canvas-design, frontend-design, brand-guidelines, theme-factory | Visual art, production-grade UI, brand colors, themed styling | | Art & Media | algorithmic-art, slack-gif-creator | Generative art with p5.js, animated GIF creation | | Documents | docx, pdf, pptx, xlsx, doc-coauthoring | Create/edit Office docs, PDFs, spreadsheets, co-author documents | | Engineering | web-artifacts-builder, mcp-builder, webapp-testing | Multi-component web apps, MCP servers, browser testing | | Meta | skill-creator, internal-comms | Create new skills, write internal communications |

Active Plugins

| Plugin | Purpose | |--------|---------| | compound-engineering | Multi-agent workflows: plan, brainstorm, review, work | | feature-dev | Guided feature development with codebase understanding | | code-review | PR review with specialized analysis agents | | pr-review-toolkit | Silent failure hunting, type design, test coverage | | code-simplifier | Post-implementation code clarity pass | | coderabbit | AI code review on changes | | hookify | Create hooks to prevent unwanted behaviors | | plugin-dev | Build and validate Claude Code plugins | | agent-sdk-dev | Verify Agent SDK applications | | claude-code-setup | Automation recommendations | | claude-md-management | CLAUDE.md auditing and improvement | | playground | Interactive HTML playground creation | | commit-commands | Commit, push, PR workflows | | github | GitHub integration |

| Plugin | Language | |--------|----------| | typescript-lsp | TypeScript/JavaScript | | pyright-lsp | Python | | gopls-lsp | Go | | clangd-lsp | C/C++ | | csharp-lsp | C# | | jdtls-lsp | Java | | kotlin-lsp | Kotlin | | lua-lsp | Lua | | php-lsp | PHP | | rust-analyzer-lsp | Rust | | swift-lsp | Swift |

| Plugin | Domain | |--------|--------| | data | SQL, dashboards, visualizations, statistical analysis | | marketing | Campaigns, brand voice, SEO, content, competitive analysis | | finance | Journal entries, reconciliation, SOX, variance analysis | | legal | Contract review, NDA triage, compliance checks | | product-management | Specs, roadmaps, sprint planning, user research | | sales | Pipeline, forecasting, outreach, competitive intel | | customer-support | Triage, research, escalation, KB articles | | enterprise-search | Cross-source search, knowledge synthesis | | productivity | Task management, memory systems | | bio-research | PubMed, ChEMBL, clinical trials, bioRxiv, scRNA-seq |

| Plugin | Purpose | |--------|---------| | ralph-loop | Autonomous agent loop | | huggingface-skills | HF Hub: models, datasets, training, evaluation | | context7 | Up-to-date library documentation | | playwright | Browser automation and testing | | frontend-design | Production-grade frontend components |

Compound Engineering Workflows

The compound-engineering plugin provides multi-agent orchestration:

| Workflow | Command | Description | |----------|---------|-------------| | Plan | /plan | Transform feature descriptions into structured plans | | Brainstorm | /brainstorm | Explore requirements through collaborative ideation | | Work | /work | Execute plans efficiently with quality gates | | Review | /review | Exhaustive multi-agent code review | | Compound | /compound | Document solved problems for future reference |

Installation

# From source
git clone https://github.com/shyamsridhar123/sharkbait.git
cd sharkbait
bun install
bun run build:binary

Prerequisites

• Bun >= 1.0.0
• Git >= 2.30
• gh (GitHub CLI) >= 2.40 (optional, for GitHub features)
• Azure OpenAI API access

Configuration

1. Set up your Azure OpenAI credentials:

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_API_KEY="your-api-key"
export AZURE_OPENAI_DEPLOYMENT="gpt-codex-5.2"

2. Or create a .env file:

cp .env.example .env
# Edit .env with your credentials

Usage

Interactive Chat

sharkbait chat

One-off Question

sharkbait ask "How do I refactor this function?"

Autonomous Task Execution

sharkbait run "Add input validation to the login endpoint"

Initialize in Project

cd your-project
sharkbait init

Slash Commands

During an interactive chat session, use slash commands for quick actions:

Navigation

| Command | Description | |---------|-------------| | /cd <path> | Change working directory (creates if needed) | | /pwd | Show current working directory |

Session

| Command | Description | |---------|-------------| | /clear | Clear message history | | /exit | Exit Sharkbait (aliases: /quit, /q) |

Configuration

| Command | Description | |---------|-------------| | /beads [on\|off] | Toggle or check Beads task tracking | | /model [name] | Show or switch the LLM model | | /tasks | Show Beads task status | | /context [add\|remove\|list] | Manage context files |

Actions

| Command | Description | |---------|-------------| | /setup | Launch interactive setup wizard | | /init | Initialize Sharkbait in current directory | | /ask <question> | Ask a one-off question | | /run <task> | Execute a task autonomously | | /review <file> | Run parallel code review (bugs, security, style, performance) |

Information

| Command | Description | |---------|-------------| | /version | Show Sharkbait version | | /help [command] | Show available commands or help for a specific command |

Example: Run a parallel code review:

> /review src/auth.ts
Starting parallel review: bugs, security, style, performance on src/auth.ts
[Progress bars for each reviewer mode]
Parallel Review Complete (12.3s)

Full Slash Commands Reference

Available Tools

Sharkbait has access to 36 tools across different categories:

| Category | Tools | |----------|-------| | File Operations | read_file, write_file, edit_file, list_directory, search_files, grep_search, create_directory | | Shell | run_command, open_file | | Beads | beads_status, beads_init, beads_ready, beads_create, beads_show, beads_done, beads_add_dependency, beads_list | | Git | git_status, git_diff, git_commit, git_push, git_branch, git_log | | GitHub | github_create_pr, github_list_prs, github_merge_pr, github_create_issue, github_workflow_status, github_pr_view, github_issue_list | | Codebase | analyze_codebase, find_dependencies, map_architecture | | Web/Fetch | fetch_webpage, fetch_json, web_search |

Specialized Agents

Sharkbait uses a multi-agent architecture with specialized agents for different tasks:

| Agent | Purpose | |-------|---------| | Orchestrator | Routes requests to the appropriate specialized agent based on intent | | Coder | Writes, modifies, and refactors code with tool access | | Reviewer | Reviews code for bugs, security, style, and performance issues | | Explorer | Maps codebase architecture and finds relevant files | | Planner | Breaks down complex tasks into actionable steps | | Debugger | Traces issues and diagnoses bugs | | Parallel Executor | Runs multiple agent tasks concurrently (e.g., parallel code reviews) |

Architecture

Sharkbait implements a sophisticated agentic loop with:

• Dual-ledger progress tracking: Inspired by Microsoft's Magentic-One research
• Intelligent context compaction: Preserves critical context while managing token limits
• Action reversibility classification: Classifies commands as easy/effort/irreversible
• Stall detection & recovery: Automatic re-planning when stuck

Tech Stack

| Component | Technology | Reason | |-----------|------------|--------| | Runtime | Bun | Fast startup, native TS | | Language | TypeScript | Type safety | | LLM | Azure OpenAI GPT Codex 5.2 | Enterprise | | Memory | Beads (built-in) | Git-backed persistence | | GitHub | git + gh CLI | No Octokit needed | | CLI UI | ink | React for terminals | | CLI Framework | commander | Argument parsing |

Development

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Type check
bun run typecheck

# Build for distribution
bun run build:binary

# Build for all platforms
bun run build:all

Configuration Options

| Environment Variable | Description | Default | |---------------------|-------------|---------| | AZURE_OPENAI_ENDPOINT | Azure OpenAI endpoint URL | (required) | | AZURE_OPENAI_API_KEY | Azure OpenAI API key (falls back to Azure Identity if unset) | (optional) | | AZURE_OPENAI_DEPLOYMENT | Model deployment name | gpt-codex-5.2 | | AZURE_OPENAI_API_VERSION | API version (Responses API requires 2025-03-01-preview+) | 2025-03-01-preview | | SHARKBAIT_LOG_LEVEL | Log level (debug/info/warn/error) | info | | SHARKBAIT_LOG_FILE | Enable file logging to ~/.sharkbait/logs | false | | SHARKBAIT_LOG_JSON | Use JSON format for console output | false | | SHARKBAIT_LOG_DIR | Custom log file directory | ~/.sharkbait/logs | | SHARKBAIT_TELEMETRY | Enable opt-in anonymous telemetry | false | | SHARKBAIT_MAX_CONTEXT_TOKENS | Max context window tokens | 100000 | | SHARKBAIT_CONFIRM_DESTRUCTIVE | Require confirmation for destructive commands | true | | SHARKBAIT_WORKING_DIR | Default working directory | (current directory) |

Logging & Monitoring

Structured Logging

# Enable debug logging
export SHARKBAIT_LOG_LEVEL=debug

# Enable file logging (writes to ~/.sharkbait/logs/sharkbait.log)
export SHARKBAIT_LOG_FILE=true

# Use JSON format for machine-readable logs
export SHARKBAIT_LOG_JSON=true

Log output includes timestamps, levels, and contextual information:

[18:55:21.545] [INFO ] [coder] Agent started processing
[18:55:21.560] [INFO ] config.load (8ms)

File Logging

When enabled, logs are written as newline-delimited JSON:

{"timestamp":"2026-01-29T18:55:21.545Z","level":"info","message":"Agent started","context":{"agent":"coder","correlationId":"abc123"}}

Features:

• Automatic rotation at 10MB (keeps 5 files)
• Structured JSON for easy parsing
• Context propagation (agent, tool, correlationId)

Performance Monitoring

Built-in metrics track:

• LLM call latencies (avg, p50, p90, p99)
• Tool execution times
• Memory usage
• Token consumption

Distributed Tracing

Trace agent execution with OpenTelemetry-inspired spans:

agent: coder (1250ms)
  llm: gpt-codex-5.2 (800ms)
  tool: file_read (45ms)
  tool: file_write (120ms)

Telemetry (Opt-in)

Anonymous usage analytics can be enabled to help improve Sharkbait:

export SHARKBAIT_TELEMETRY=true

What's collected: Event counts (sessions, tool usage), latency metrics What's NOT collected: File paths, code content, prompts, personal info

Configuration File

Sharkbait stores configuration in ~/.sharkbait/config.json. Example:

{
  "azure": {
    "deployment": "gpt-codex-5.2"
  },
  "features": {
    "beads": true,
    "confirmDestructive": true
  },
  "paths": {
    "defaultWorkingDir": "/path/to/your/project"
  }
}

Generative Art Gallery

Created with the algorithmic-art and canvas-design skills:

Security

Sharkbait includes multiple layers of security:

1. Blocked commands: Dangerous patterns like rm -rf / are blocked
2. Reversibility classification: Commands are classified by how easy they are to undo
3. Confirmation prompts: Destructive operations require confirmation
4. Secret redaction: API keys and passwords are not logged

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions welcome! Please see the backlog in backlog/tasks/ for open items.