Skip to main content

Cmdora

Cmdora is a Windows command-line assistant for careful Git and workspace workflows. You describe an intent in plain English; Cmdora either selects a deterministic supported workflow or asks Gemini for a structured plan only. Local checks decide whether a command may run.

Cmdora is a pre-alpha developer tool. Use it in a disposable repository while you evaluate it.

Terminal work is often slowed by remembering exact Git and PowerShell syntax. An LLM can help translate intent, but it must not become an unrestricted shell authority. Cmdora keeps planning, policy, approval, execution, and audit logging separate.

Features

  • Plain-English workflows for file creation, files modified today, Git status, commits, pushes, and explain-only Git questions.
  • Gemini plans validated against strict Pydantic schemas.
  • Workspace-constrained PowerShell execution with no user profile, a timeout, captured output, and Ctrl+C handling.
  • Local command allowlist and explicit blocks for deletion, encoded PowerShell, secrets, remote downloads, package installs, remote changes, force pushes, and other unsafe operations.
  • Per-repository constrained autonomy for safe reads, new allowed workspace files, and guarded Git work.
  • SQLite audit history with secret redaction.
  • Offline unit and integration tests, plus an opt-in live Gemini evaluation corpus.

Architecture

flowchart TD
    R[Plain-English request] --> D{Deterministic workflow?}
    D -->|Yes| P[Local policy and path validation]
    D -->|No| C[Build redacted safe context]
    C --> G[Gemini structured ActionPlan]
    G --> V[Pydantic schema validation]
    V --> L[Display plan only]
    P --> B{Allowed?}
    B -->|No| X[Blocked result + audit record]
    B -->|Yes, write/Git action| A[User approval or scoped autonomy]
    B -->|Yes, read-only| E[Bounded executor]
    A --> E
    E --> H[Redacted SQLite audit history]
    L --> H
    X --> H

Gemini receives only redacted request text and narrow repository metadata: workspace basename, Git state, supported actions, and autonomy mode. It does not receive file contents, .env values, tokens, SSH keys, personal paths, or complete Git diffs.

Installation

Requirements: Windows PowerShell, Python 3.12+, Git, and uv.

git clone https://github.com/indrasuthar07/Cmdora.git
Set-Location Cmdora
uv sync --all-extras
uv run Cmdora --help

Gemini API key setup

Anyone using Cmdora can configure their API key once with a single command:

cmdora config set-key

You will be prompted securely for your key, which is saved to %APPDATA%\CmdoraAI\.env so Cmdora works from any folder or repository. You can also pass it directly:

cmdora config set-key "your-gemini-api-key"

Alternatively, set GEMINI_API_KEY in a local .env file or export it for your terminal session:

$env:GEMINI_API_KEY = "your-key-here"

Gemini is needed only for requests that are not handled by a deterministic built-in workflow.

Example commands

Run Cmdora from the repository you want it to operate on:

Cmdora "list all files modified today"
Cmdora "what command shows my current git branch?"
Cmdora "create src/components/Button.js"
Cmdora "create src/components/Button.js" --dry-run
Cmdora "git status"
Cmdora "commit my latest changes with message add button component"
Cmdora "push my current branch"
Cmdora history --last 10

For a safe first run, use --dry-run; it shows the proposed deterministic command without starting PowerShell.

Autonomous mode

Cmdora defaults to approval mode for non-read-only actions. Enter a at an approval prompt and confirm the additional warning to enable git autonomy for the current repository. Cmdora stores that decision only in .Cmdora/config.toml inside that workspace.

Cmdora "create src/utils/date.py" --autonomy git

Autonomy can run safe reads, new allowed workspace files, and permitted Git operations. It cannot run arbitrary shell commands, delete files, read secrets, leave the workspace, force-push, or push to protected branches such as main and master.

Security model

Cmdora treats generated content as untrusted. It validates paths, classifies commands locally, uses an allowlist, requires confirmation for state-changing actions, and records redacted results. The local policy blocks destructive commands, obfuscated PowerShell, credential paths, .env access, downloads, package installs, force pushes, branch deletion, and remote changes.

Audit data is stored at %APPDATA%\CmdoraAI\history.db; use Cmdora history to inspect it. The audit redactor removes common API keys, bearer tokens, JWT-like strings, password values, SSH private-key text, .env values, and the full home-directory path.

Limitations

  • Windows PowerShell is the supported shell; Cmdora does not support Bash, macOS, or Linux yet.
  • Cmdora supports a deliberately small command set and will not execute arbitrary natural-language requests.
  • Git pushes require a non-protected branch, configured origin, explicit push intent, and policy validation.
  • Gemini availability, quotas, and model access are external dependencies for planning requests.
  • The live Gemini evaluation is opt-in and has not been bundled with normal tests.

Testing

uv run pytest -q
uv run ruff check src tests scripts
uv run mypy

The suite includes temporary workspace and Git repositories, a local bare Git remote, real PowerShell timeout/exit-code checks, policy tests, and a 61-prompt safety corpus. GitHub Actions runs the offline checks on pushes and pull requests. Details and the opt-in live evaluation are in docs/evaluation.md.

Roadmap

  • Execute validated structured multi-step plans through the same policy gate.
  • Add richer repository inspection and safe read-only workflows.
  • Add cross-platform shell support.
  • Add a reviewed public demo GIF/video and release artifact.
  • Add CI coverage reporting and release automation.

Contributing

  1. Create a feature branch from main.
  2. Keep the change focused and add tests for behavior changes.
  3. Run the commands in Testing.
  4. Open a pull request describing the safety impact and verification results.

Never commit .env, API keys, generated local audit databases, virtual environments, or cache directories.

License

Cmdora is released under the MIT License.

Metadata

Release files for cmdora 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cmdora 0.1.0
File Size Uploaded Provenance Actions
cmdora-0.1.0.tar.gz 139.4 kB Without provenance Details for cmdora-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cmdora 0.1.0
File Interpreter ABI Platform Actions
cmdora-0.1.0-py3-none-any.whl Python 3 none any Details for cmdora-0.1.0-py3-none-any.whl

Total release size: 189.5 kB

Release files / cmdora-0.1.0.tar.gz

Download URL cmdora-0.1.0.tar.gz
Size 139.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f5f673d061b82f3ce5fbc7394eb286cbd7641e83e040312e7589ecf6f230b093
BLAKE2b-256 checksum
How to use checksums
a08fc2640cf7350a67279a3eb900991efe6268b1361e94d778f7809d1aa44ca8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.23 {"installer":{"name":"uv","version":"0.11.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / cmdora-0.1.0-py3-none-any.whl

Download URL cmdora-0.1.0-py3-none-any.whl
Size 50.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5830b71172ff3a7d40d7fc484441f0ab595d67a1a1de7018e25b794af5aa8fe5
BLAKE2b-256 checksum
How to use checksums
62e44e4142ec12a87c135c8a72b2d0744ef3a195d34ca6c70de3c38d03518a71
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.23 {"installer":{"name":"uv","version":"0.11.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for cmdora 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page