Back to Projects

AI workflow and safety layer for OpenCode

BitsentryAI is a local workflow and safety layer for OpenCode. It turns generic AI coding sessions into more structured, auditable and context-aware workflows for software design, repository research, operational support and security review.

It is not meant to be “another magic agent”. It comes from a practical friction: once you start using agents for serious work, you accumulate prompts, skills, MCPs, rules, memory, checklists and guardrails across too many places.

BitsentryAI tries to turn that chaos into a local system: a capability pack for OpenCode with an agent, commands, flows, skills, roles, route decision previews, readiness checks and explicit boundaries.

What problem it solves

AI agents are useful, but they usually create three problems in real projects:

  • 1.Lack of explicit intent: the agent receives a request and often starts acting without declaring whether it is researching, designing, triaging, reviewing security or applying changes.
  • 2.Poor separation between types of work: a feature, a bug, an AppSec review and a handoff should not follow the same path.
  • 3.Unclear boundaries: if an agent can read, edit, run commands or touch sensitive areas without visible gates, the workflow becomes hard to control.

    • BitsentryAI forces one question before acting:

    What kind of work are we actually doing?

    That question is the foundation of the project. First choose the route. Then load the right capabilities. Then work with structured outputs and explicit permissions.

    What it encourages

    BitsentryAI encourages a less impulsive and more engineering-oriented way to use AI:

  • less giant prompting for everything,
  • more declared intent,
  • more reusable context,
  • clearer separation between research, design, support, security and apply,
  • more reviewable outputs,
  • more human control before sensitive actions.

    • It is not about making the agent “do more things alone”. It is about making the agent work better inside clear boundaries.

    How it works

    The conceptual flow is simple:

    text
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 9, Col 1UTF-8

    The bitsentry agent acts as an orchestrator inside OpenCode. Its job is not to edit by default, but to classify intent, show a route decision, propose the right flow and ask for confirmation when an action may have impact.

    Main flows

  • SDD — Software Design Development: for designing and developing features through exploration, proposal, specification, design, apply and verification.
  • SDR — Software Design Research: for investigating repositories, architecture, technical debt, decisions and context before touching code.
  • Support: for triage, handoff, operational continuity, session closure and reusable summaries.
  • Source Security Review: for source code security review with a read-only-first posture.
  • Web Assessment Planning: for planning authorized and bounded assessments. It is not live execution by default.

    • Architecture decisions

    OpenCode-first

    BitsentryAI starts with OpenCode because that is where the work happens: the local repository, the development agent and the real project context. Instead of creating a separate platform, it integrates as a layer on top of the environment the developer already uses.

    Local-first

    The MVP is designed to install and operate locally. This reduces dependency on a central backend, keeps control close to the user and makes it easier to reason about what gets installed, what gets modified and what permissions exist.

    Capability pack, not hidden autonomous runtime

    One important decision is that BitsentryAI does not try to be an autonomous runtime acting behind the scenes. It is a local pack that projects capabilities into OpenCode:

    text
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 10, Col 1UTF-8

    The CLI exists as a support, diagnostics and plumbing surface. The primary experience is intended to be TUI + OpenCode.

    Explicit routing

    Route decision previews are both a product and architecture decision. Before deep discovery, planning or changes, the agent must declare how it understands the request.

    This prevents ambiguous prompts from turning directly into code edits or command execution without enough context.

    Optional persistence

    Engram can provide persistent memory for decisions, learnings, failures and historical context. Context7 can provide up-to-date external documentation when a decision depends on APIs or libraries.

    Both integrations are optional: useful when available, but not required for the MVP core.

    Technology and why

  • Go: makes it possible to ship a simple, fast local binary.
  • Bubble Tea: fits a guided TUI installer with clear steps, readiness checks and control before applying changes.
  • OpenCode: the initial target environment; BitsentryAI does not replace it, it “vitaminizes” it with workflows and guardrails.
  • Markdown: flows, skills, roles and commands remain readable, versionable and easy to review.
  • MCP: models integrations such as Engram or Context7 without mixing them into the product core.
  • Engram: provides persistent memory when a flow needs to remember decisions or lessons across sessions.
  • Context7: helps retrieve current documentation without putting everything into one giant prompt.

    • Installed OpenCode surface

    A native setup can register the bitsentry agent and /bit-* commands such as:

  • /bit-install-check
  • /bit-pack-status
  • /bit-sdd-init
  • /bit-sdr-capture
  • /bit-support-triage

    • The expected agent posture is safe by default:

    json
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 11, Col 1UTF-8

    This reinforces a key idea: BitsentryAI can guide, investigate and structure the work, but impactful actions need explicit approval.

    Current MVP features

    The public MVP includes:

  • TUI-first installer,
  • OpenCode and local state detection,
  • capability pack export,
  • bitsentry agent,
  • /bit-* commands,
  • SDD, SDR, Support, Source Security Review and Web Assessment Planning flows,
  • specialized skills and roles,
  • route decision previews,
  • readiness checks,
  • optional Engram and Context7 integration,
  • doctor/status tooling,
  • guardrails for security and sensitive actions.

    • Safety by design

    BitsentryAI is intentionally conservative. It is not an automated pentesting platform, not a scanner, does not execute exploits and does not try to operate as an unsupervised autonomous agent.

    Current MVP guardrails:

  • no hidden autonomous runtime,
  • no .env or secret access,
  • no credential extraction,
  • no live web execution by default,
  • no integrated crawler/scanner/fuzzer,
  • no one-click pentest,
  • no destructive actions,
  • manual confirmation before impactful changes.

    • For security work, this is not a side limitation: it is a central decision. First control, then capability, and automation only where it is explicit and safe.

    Technical debt and current limits

    BitsentryAI is in Public MVP, so it still has important debt and limits:

  • OpenCode-only for now: support for other agent environments comes later.
  • CLI as support/debug: it exists, but the primary UX should remain TUI + OpenCode.
  • Workflows are still evolving: SDD, SDR and Support can gain more real primitives, traceability and visible state.
  • Routing heuristics can improve: route previews exist, but classification can evolve with more signals and capability ranking.
  • Controlled integrations: Engram, Context7 and MCP should keep respecting no-secret and no-credential-mutation boundaries.
  • Limited Web Assessment posture: the MVP prioritizes planning, preflight and gates; it does not sell automatic offensive execution.
  • Living documentation: README, architecture docs, prompts and guardrails must stay aligned with real behavior.

    • This debt does not invalidate the project; it defines the next stage.

    How an AI should improve this project

    If someone wanted to pass this project to an AI to improve it, the right brief would be:

  • 1.Keep BitsentryAI OpenCode-first and local-first.
  • 2.Do not turn it into a hidden autonomous runtime.
  • 3.Preserve the separation between flows: SDD, SDR, Support, Source Security Review and Web Assessment Planning.
  • 4.Respect the guardrails: no secrets, no .env, no automatic pentesting, no live execution by default.
  • 5.Improve routing clarity, readiness checks, flow traceability and skill quality first.
  • 6.Any new automation must have preview, confirmation, backup where relevant and auditable output.
  • 7.Do not promise capabilities that are not implemented.

    • Reasonable roadmap

    The natural direction of the project is:

  • 1.stabilize the OpenCode-first MVP,
  • 2.improve guided workflows and safety contracts,
  • 3.harden Source Security Review and Web Assessment Planning,
  • 4.improve capability ranking and skill selection,
  • 5.expand integrations only after the safety model is solid,
  • 6.later, support other agent environments beyond OpenCode.

    • Current status

    BitsentryAI is currently in Public MVP. It already has a clearer product narrative, public quickstart, readiness checks, architecture documentation and explicit boundaries.

    The goal is to keep it practical: helping people work with more structure without replacing technical judgment with an agent. Feedback, ideas and PRs are welcome, especially from people using AI agents in software development, AppSec, bug bounty, technical research or workflow automation.

    Links

  • Landing: ai.bitsentry.xyz
  • GitHub: github.com/andrade-fs/bitsentry-ai
    • _BitsentryAI is about agents that do not only execute, but first understand what kind of work they are doing._