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.1

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.1
File Size Uploaded Provenance Actions
cmdora-0.1.1.tar.gz 142.0 kB Without provenance Details for cmdora-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 193.8 kB

Release files / cmdora-0.1.1.tar.gz

Download URL cmdora-0.1.1.tar.gz
Size 142.0 kB
Tags Source
SHA-256 checksum
How to use checksums
6b30145da60464f81cbc8434f2710801f6cca6bac70a47d1f75fc0f52a2a26b8
BLAKE2b-256 checksum
How to use checksums
ec8c9d8e40ee8452f9e2d2258e293f5a4303534169507659fd12f4d276f777f1
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.1-py3-none-any.whl

Download URL cmdora-0.1.1-py3-none-any.whl
Size 51.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2a6694a12218be0ce19783316bff1ef4b00fd6b0b3250483550f8f9430d0b56d
BLAKE2b-256 checksum
How to use checksums
dd9f5186ef7244124457cf519bfee15eab2e5ddf9fdb3d4d4ac6e86b08402b98
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.1

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.1 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