import vibewithai

vibewithai.login("sk-proj-...", "AIza...", "sk-ant-...")   # any keys, any order

result = vibewithai.check()

print(result.score)      # 87
print(result.summary)    # "3 issues found across 12 files (1 at or above high)."

You describe an engineering task. The SDK handles provider selection, context building, token budgeting, retries, and failover.

Why vibewithai

Most AI coding tools are a prompt box with a system message. This is a working SDK with an opinion about how AI should be used on real codebases.

Installation

pip install vibewithai

That is everything. Ruff, Bandit, Radon and LibCST come with it, so the first vibewithai check finds real problems rather than reporting that its analyzers are missing.

Requires Python 3.11+. Tested on 3.11–3.14 across Linux, macOS and Windows.

Eight runtime dependencies: httpx, platformdirs, rich and typer for the SDK itself, and ruff, bandit, radon and libcst for the analysis that runs before any model is consulted. No vendor SDKs — all 16 providers are reached over plain HTTP, so adding one costs nothing at install time.

None of them is imported by import vibewithai, which is why the import stays around 2 ms whether or not an analyzer ever runs.

Quick start

1. Authenticate

import vibewithai

vibewithai.login(
    "sk-proj-xxxxxxxx",   # OpenAI
    "AIzaSyxxxxxxxx",     # Google Gemini
    "xai-xxxxxxxx",       # xAI Grok
    "sk-ant-xxxxxxxx",    # Anthropic
)

Or keep keys out of your code entirely:

export VIBEWITHAI_OPENAI_API_KEY=sk-proj-...
export ANTHROPIC_API_KEY=sk-ant-...          # conventional vendor variables work too

vibewithai.login()    # environment → stored credentials → local Ollama

Guided terminal setup:

vibewithai init

2. Run a task

result = vibewithai.review("src/app.py")

for finding in result.findings_at_or_above(vibewithai.Severity.HIGH):
    print(f"{finding.location}  [{finding.severity}]  {finding.title}")
    print(f"    {finding.detail}")
    print(f"    via {finding.source} (confidence {finding.confidence})")

finding.source tells you whether a result came from a deterministic tool ("ruff", "bandit") or a model ("ai:openai"), so you always know how much to trust it.

3. Gate on it

result = vibewithai.security()

if not result:                 # falsy only when the tool itself errored
    raise SystemExit(2)
if not result.passed:          # False when blocking findings exist
    raise SystemExit(result.exit_code)

The API

Twenty commands, grouped by intent. Every one returns a CommandResult.

Understand

vibewithai.check()                    # full quality assessment, scored 0–100
vibewithai.review("src/app.py")       # pull-request style review
vibewithai.explain("src/auth.py")     # what it does and why
vibewithai.ask("Why is login failing?")
vibewithai.chat("How should I structure this service?")

Improve

vibewithai.fix("src/app.py")          # propose corrections
vibewithai.refactor("src/app.py")     # restructure, behaviour preserved
vibewithai.optimize()                 # find real performance problems
vibewithai.comment("src/app.py")      # docstrings where they are missing

Secure and ship

vibewithai.security()                 # vulnerability audit with exploitability reasoning
vibewithai.deploy()                   # production-readiness assessment
vibewithai.debug("KeyError: user_id", traceback=tb)

Create

vibewithai.test("src/app.py")         # generate pytest tests
vibewithai.document()                 # API reference
vibewithai.readme()                   # project README
vibewithai.generate("a FastAPI CRUD API for users")
vibewithai.coverage()                 # measure via pytest --cov

Converse and stream

session = vibewithai.chat()                       # a session that remembers
session.ask("Where is authentication handled?")
session.ask("Can we improve it?")                 # "it" resolves to the answer above

with vibewithai.stream("Explain the request flow") as answer:
    for chunk in answer:
        print(chunk, end="", flush=True)          # arrives as it is written

Version control

vibewithai.commit()                   # Conventional Commits message from staged diff
vibewithai.changelog(since="v1.2.0")  # Keep a Changelog entry

Commands that produce files write nothing unless you pass apply=True:

result = vibewithai.fix("src/app.py")
print(result.artifacts["src/app.py"])          # review first
vibewithai.fix("src/app.py", apply=True)       # then apply; original is backed up

Command line

vibewithai                            # welcome screen with detected environment
vibewithai init                       # guided setup
vibewithai doctor                     # diagnose the installation
vibewithai tutorial                   # learn the commands in five minutes

vibewithai check                      # exits 1 on findings at or above `high`
vibewithai review src/app.py
vibewithai security --fail-on medium
vibewithai fix src/app.py --yes

vibewithai ask "how does auth work?" --stream

vibewithai check --format json        # machine-readable
vibewithai check --format sarif       # GitHub Code Scanning
vibewithai check --format junit       # CI test-report views
vibewithai check --format github      # inline PR annotations, no token needed
vibewithai review --changed-only      # only files changed from HEAD

Exit codes: 0 clean · 1 findings at or above the threshold · 2 execution error.

Result objects

result = vibewithai.check()

result.score              # 0–100 quality score
result.status             # Status.WARNING
result.summary            # human-readable paragraph
result.findings           # list[Finding] — severity, location, source, confidence
result.suggestions        # list[Suggestion] — title, rationale, effort
result.metrics            # files, lines, complexity, cache hit rate
result.usage              # prompt/completion/cached token accounting
result.provider           # "openai"
result.execution_time     # seconds

result.passed             # quality gate
result.exit_code          # POSIX exit code
result.counts_by_severity # {'critical': 0, 'high': 1, ...}
result.findings_at_or_above(vibewithai.Severity.HIGH)

result.to_dict()          # JSON-serialisable, safe to log
result.to_json()

Render to any format:

from vibewithai.reports import render

open("report.html", "w").write(render(result, "html"))
open("report.md", "w").write(render(result, "markdown"))

Supported providers

All 16 work with an API key alone. No vendor SDKs, and no per-provider packages — adding a provider never changes what you install.

Provider selection, key detection and failover are entirely automatic. Adding a new OpenAI-compatible provider is a single entry in providers/specs.py.

Not yet supported: AWS Bedrock, Google Vertex AI and OCI Generative AI require cloud-native request signing (SigV4, service-account JWTs) rather than bearer tokens. Reach those models through OpenRouter or an OpenAI-compatible gateway in the meantime.

Configuration

Layered, highest precedence first: call arguments → environment → project file → user file → defaults.

# vibewithai.toml
default_provider   = "openai"        # omit to use the first verified provider
offline            = false           # true = local static analysis only
max_context_tokens = 12000

[providers.openai]
model = "gpt-4o-mini"

[analysis]
analyzers         = ["ast", "ruff", "bandit", "radon"]
blocking_severity = "high"
exclude           = [".venv", "node_modules", "*_pb2.py"]

[auth]
fallback        = true               # switch providers on rate limits and outages
preferred_order = ["anthropic", "openai"]

[cache]
enabled = true
ttl     = 86400

Credentials are never read from project files — only from environment variables and the user-level credential store — so a key cannot be committed by accident. Full reference: the configuration guide.

Enterprise considerations

Security

• Credentials never leak. API keys are wrapped in a Secret type that masks itself in str(), repr(), f-strings, and refuses to pickle. Independently, a logging filter scrubs credential-shaped text from every record before emission.
• Nothing is written without consent. Commands that modify the workspace raise ConfirmationRequiredError unless explicitly authorised; originals are backed up; writes outside the project root are refused; every write is atomic.
• AI output is never executed. Not eval-ed, not exec-ed, not imported.
• Owner-only credential storage — 0600 file inside a 0700 directory, with a warning if permissions loosen.
• Full threat model: SECURITY.md.

Data governance

Any AI command sends a bounded, relevant slice of your code — the file in question plus its direct collaborators — never the whole repository. For codebases that must not leave your network:

offline = true    # local static analysis only; zero network calls

Or run entirely on local models via Ollama.

CI/CD

- run: pip install vibewithai
- run: vibewithai check --fail-on high --format json > report.json
  env:
    VIBEWITHAI_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Ready-made configurations for GitHub Actions, GitLab CI, Jenkins and Azure DevOps, plus a fuller GitHub Actions walkthrough covering Code Scanning, test reports and per-pull-request AI review.

Performance

Analysis results are cached against file content digests, so unchanged files are never re-analysed and never re-sent to a model. Independent files are analysed in parallel. Repeat runs on a large repository complete in milliseconds.

Extensibility

from vibewithai.plugins import register

register(provider=my_provider_spec)                  # an AI backend
register(analyzer=MyAnalyzer())                      # a static check
register(report_format="teamcity", renderer=render)  # an output format
register(event_sink=my_telemetry)                    # progress and audit events
register(task=my_task_spec)                          # a whole new command

A task added this way runs on the same engine as every built-in command — no engine change is involved, because a command is its declaration. Nothing may replace a built-in: a name collision raises rather than silently redefining a documented command.

Plugins are discovered through the vibewithai.plugins entry-point group, on the first analysis of a process rather than at import, so import vibewithai stays free of side effects.

Documentation

Project health

Status

1.1.2. The full pipeline is implemented, tested end to end, and the public surface is stable — output shapes are pinned by golden tests, every promise in SECURITY.md has a test named after it, and both the module layering and the repository layout are enforced by tests rather than described in prose.

The AI-backed commands still have far more automated testing than real-world mileage. Treat their output as a capable reviewer's opinion rather than ground truth — which is exactly why every finding carries a confidence score and a source. Deterministic static analysis is unaffected by this caveat, and it is what check runs on.

Issues and feedback: github.com/ragulraj-d/vibewithai/issues

Contributing

Contributions are welcome — see CONTRIBUTING.md and the Code of Conduct. To report a vulnerability, follow SECURITY.md rather than opening a public issue.

License

MIT