Features

A complete reference to everything ByteAsk can do. All features documented here exist in the shipped binary; nothing is speculative.

---

Interactive TUI

The default mode. ByteAsk opens a full-screen terminal UI (built with Ratatui + Crossterm) that shows:

• A streaming conversation pane with the model's reasoning and tool calls
• An approval prompt whenever the agent wants to run a shell command or edit a file
• A status line showing the current model, token usage, and session name
• A composer (the input box) at the bottom, with optional Vim keybindings

byteask                         # open TUI (starts with empty prompt)
byteask "fix the null deref"    # open TUI with an initial prompt

The TUI supports slash commands (see Slash Commands), /plan mode for structured multi-step tasks, and side conversations via /side or /btw.

---

Non-interactive / Scripting mode

Use byteask exec for CI pipelines, shell scripts, or any automation where you don't want the TUI:

byteask exec "add unit tests for parser.cpp"
byteask exec - < prompt.txt                    # read prompt from stdin
byteask exec --json "refactor the config"      # JSONL output on stdout

Key exec flags:

Flag	Description
--json	Print events as JSONL (one event per line)
-o FILE	Write the agent's final message to a file
--ephemeral	Run without writing any session files to disk
--ignore-user-config	Skip ~/.byteask/config.toml
--ignore-rules	Skip .rules files in the project
--output-schema FILE	Constrain the model's final response to a JSON Schema
--skip-git-repo-check	Allow running outside a Git repo

---

Approval modes

ByteAsk asks for your approval before taking actions. The policy is set via --ask-for-approval (or approval_policy in config):

Mode	CLI value	Behavior
On request	on-request	Default. The model decides when to ask; most read-only actions proceed silently
Untrusted	untrusted	Only known-safe read-only shell commands auto-approve; everything else requires confirmation
Never	never	Never interrupt; failures are fed back to the model automatically

byteask --ask-for-approval untrusted "audit the build system"
byteask --ask-for-approval never "run all the tests and fix failures"

You can also bypass all approvals (use with care):

byteask --dangerously-bypass-approvals-and-sandbox "..."
# or the alias:
byteask --yolo "..."

The /approve slash command lets you approve a single retry mid-session without changing the global policy.

---

Sandboxing

ByteAsk sandboxes the shell commands it runs:

• Linux: bubblewrap (bwrap). Installed automatically by install.sh. Falls back to --sandbox danger-full-access if bwrap is unavailable.
• macOS: Native macOS Seatbelt — no extra install required.

Sandbox modes, set via --sandbox:

Mode	Flag value	Description
Read-only	read-only	Default. Agent can read any file but cannot write outside approved paths
Workspace write	workspace-write	Agent can write anywhere inside the current working directory
Full access	danger-full-access	No filesystem restrictions

byteask --sandbox workspace-write "generate test fixtures"

warning

sandbox_mode in config.toml is a legacy integer field. String sandbox values must go through the --sandbox CLI flag.

---

C/C++ tooling

ByteAsk ships 18 built-in tools for the C and C++ ecosystem. They are available in every session:

Compiler tools

Tool	Description
cpp_compile_db	Generate or update compile_commands.json (via bear/cmake/ninja)
cpp_nav	Semantic navigation via clangd LSP (go-to-definition, find-references)
cpp_godbolt	Compile and disassemble on Compiler Explorer with friendly compiler names and library resolution
cpp_insights	Run C++ Insights to expand templates, lambdas, and range-for loops

Static analysis

Tool	Description
cpp_tidy	Run clang-tidy with your .clang-tidy config
cpp_format	Apply clang-format formatting
cpp_check	Run cppcheck static analysis

Dynamic analysis

Tool	Description
cpp_sanitize	Build and run with ASan, UBSan, TSan, or Valgrind
cpp_debug	Run gdb or lldb in batch mode (breakpoints, backtraces, expressions)
cpp_debug_attach	AI pair-debugging: attach to a live gdb session already running on your process
cpp_record	Record a deterministic trace with rr

Profiling

Tool	Description
cpp_perf	Profile with Linux perf or Callgrind
cpp_bench	Micro-benchmark via QuickBench

Binary analysis

Tool	Description
cpp_binary	Inspect binaries with objdump, nm, and readelf
cpp_symbolize	Symbolize addresses with addr2line (PIE-aware)
cpp_decompile	Decompile with Radare2 or Ghidra

Reference

Tool	Description
cpp_intrinsic	Look up Intel intrinsics from the full 7 126-entry dataset

Online tools (cpp_godbolt, cpp_insights, cpp_bench) call their respective public APIs directly from your machine, so no gateway round-trip is needed.

gdb attach

cpp_debug_attach lets ByteAsk drive a gdb session you already have open. Start gdb on your process, then prompt ByteAsk to attach — it reads thread state, evaluates expressions, and proposes fixes without touching your session's control flow.

---

Session management

Every TUI conversation is persisted in a local SQLite database under ~/.byteask/.

CLI subcommands

byteask resume            # interactive picker of saved sessions
byteask resume <id>       # resume a specific session by ID
byteask fork <id>         # branch off a previous session
byteask archive <id>      # archive (hide from default list)
byteask unarchive <id>    # restore an archived session
byteask delete <id>       # permanently delete a session

Inside the TUI, use /resume, /fork, /archive, /delete, or /new (start a fresh session without exiting).

---

Multimodal input

Attach one or more images to your prompt:

byteask --image screenshot.png "what's wrong with this output?"
byteask -i diagram.png -i callstack.png "explain the crash"

The model receives the image as part of the first message. Supported on any model whose catalog entry lists "image" in input_modalities.

---

Model configuration

Selecting a model

byteask --model gpt-5.4 "..."        # per-invocation
byteask -m claude-opus-4-8 "..."

Or set it permanently in config:

~/.byteask/config.toml

model = "gpt-5.4"

Inside the TUI, use /model to open an interactive model picker. The picker shows all models in your catalog with their context window and capabilities.

Reasoning effort

# "none" | "minimal" | "low" | "medium" (default) | "high" | "xhigh" | "ultra"
model_reasoning_effort = "medium"

Model catalog

ByteAsk uses a JSON model catalog (~/.byteask/models-catalog.json) to extend the built-in model list with provider metadata. The catalog is fetched automatically on first install and on byteask login. It currently includes models from OpenAI, Anthropic (Claude), and Google (Gemini).

---

Web search

ByteAsk can search the web while answering your prompt:

byteask --search "what's the latest clang-tidy check for modernize-use-ranges?"

Or enable it persistently:

~/.byteask/config.toml

# "disabled" | "cached" (default) | "indexed" | "live"
web_search = "live"

Additional web search options:

[tools.web_search]
context_size = "medium"    # "low" | "medium" | "high"
allowed_domains = ["cppreference.com", "isocpp.github.io"]

---

MCP support

ByteAsk implements the Model Context Protocol on both sides:

• As a client: connect to any external MCP server and use its tools.
• As a server: expose ByteAsk's capabilities to other MCP clients via byteask mcp-server (stdio transport).

Connecting an MCP server

~/.byteask/config.toml

[mcp_servers.my-server]
command = "/usr/local/bin/my-mcp-server"
args = ["--port", "8080"]
env = { MY_ENV_VAR = "value" }
enabled = true

Or use HTTP/SSE transport:

[mcp_servers.remote-server]
url = "https://example.com/mcp"
bearer_token_env_var = "MY_SERVER_TOKEN"

Manage servers from the CLI

byteask mcp list
byteask mcp add <name> <command> [args...]
byteask mcp remove <name>

Inside the TUI, use /mcp to list active MCP servers and their tools, or /mcp verbose for full tool schemas.

Run ByteAsk as an MCP server

byteask mcp-server

This starts ByteAsk in stdio MCP server mode, allowing any MCP-compatible client (Cursor, Claude Desktop, etc.) to use ByteAsk as a tool.

---

Plan mode

Switch the agent into an explicit planning mode where it drafts a step-by-step plan before executing:

/plan

You can review and edit the plan before execution begins. Plan mode uses a separate (higher) reasoning effort by default, configurable via:

plan_mode_reasoning_effort = "high"

---

Multi-agent / side conversations

Slash command	Description
/agent	Switch the active agent thread
/subagents	List all running agent threads
/side or /btw	Start an ephemeral fork side conversation — ask a quick question without interrupting the main task

---

Memories

ByteAsk can remember facts across sessions. Use /memories to view, add, edit, or delete memories. Memories are stored locally and injected into future system prompts.

~/.byteask/config.toml

[memories]
enabled = true

---

Hooks

Lifecycle hooks let you run shell commands at specific points in a ByteAsk session (e.g. before the agent edits a file, after it finishes a turn):

~/.byteask/config.toml

[hooks]
pre_tool_call = ["echo 'about to call a tool'"]
post_tool_call = ["./notify.sh"]

Manage and inspect hooks with the /hooks slash command.

---

Profiles

Named profiles let you switch between config presets:

~/.byteask/config.toml

[profile.ci]
approval_policy = "never"
sandbox = "workspace-write"
model = "gpt-5.4"

byteask --profile ci "fix all test failures"

---

Vim mode

Enable Vim keybindings in the TUI composer:

/vim           # toggle Vim mode for the current session

Or make it the default:

~/.byteask/config.toml

[tui]
vim_mode_default = true

---

Shell environment policy

Control which environment variables are passed to the agent's shell:

~/.byteask/config.toml

[shell_environment_policy]
inherit = "core"          # "all" | "core" | "none"
exclude = ["SECRET_KEY"]
set = { CI = "true" }
include_only = ["PATH", "HOME", "CC", "CXX"]

---

Plans, usage & credit

ByteAsk accounts run on a usage-metered plan. You can see and manage everything from inside the TUI with the ByteAsk account slash commands.

Usage windows

Usage is metered over two windows that reset independently:

Window	Resets
5-hour	A rolling 5-hour budget
Weekly	A rolling 7-day budget

Check your remaining budget any time with /usage — it shows a percentage bar and the exact reset time for each window.

Plans

Plan	Price	Usage
Free	$0	Base monthly usage
Pro	$20/mo	More usage than Free
Max	$100/mo	Highest usage

Upgrade in place with /upgrade pro or /upgrade max. Your plan activates automatically once payment completes.

Credit ("Extra usage")

Beyond your plan you can hold account credit, shown as the Extra row in /usage. Credit is spent automatically once your plan's 5-hour and weekly budgets are exhausted, so it extends your usage rather than replacing it. Two ways to earn it:

• Referrals — /referral-code prints your code plus share commands. Every person who installs with your code and signs up earns you $10 of credit.
• Vouchers — /voucher <code> redeems a voucher for a one-time credit top-up.

note

Everything about plans and usage is enforced server-side, so it applies to every client the moment it changes. The client never sees dollar amounts for plan usage — only percentages. The single exception is the credit balance, which is inherently a dollar amount.

---

BYOK (Bring Your Own Key)

Use your own OpenAI, Anthropic, or Gemini API key. Your key is stored locally (~/.byteask/byok-config.json, mode 0600) and traffic goes directly to the provider — it never passes through ByteAsk's servers.

byteask byok set         # interactive key setup
byteask byok status      # show which models use BYOK vs managed
byteask byok remove      # remove a stored key
byteask byok off         # disable BYOK for all models

---

Shell completions

Generate tab completions for your shell:

byteask completion bash   >> ~/.bashrc
byteask completion zsh    >> ~/.zshrc
byteask completion fish   >> ~/.config/fish/completions/byteask.fish

---

Diagnostics

byteask doctor            # check installation, config, auth, and connectivity
byteask debug             # sub-tool for inspecting models, traces, and config
byteask features          # list all feature flags and their current state