thetaterm 0.1.1__tar.gz

thetaterm-0.1.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

thetaterm-0.1.1/NOTICE

@@ -0,0 +1,7 @@
+Copyright 2026 ThetaPlex
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

thetaterm-0.1.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: thetaterm
+Version: 0.1.1
+Summary: Supercharge your terminal with AI
+Keywords: shell,terminal,cli,llm,ollama,natural-language
+Author: ThetaPlex
+Author-email: ThetaPlex <support@thetaplex.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: rich>=14.1.0
+Requires-Dist: typer>=0.17.3
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/thetaplex/thetaterm
+Project-URL: Documentation, https://github.com/thetaplex/thetaterm/tree/main/docs
+Project-URL: Issues, https://github.com/thetaplex/thetaterm/issues
+Project-URL: Changelog, https://github.com/thetaplex/thetaterm/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Thetaterm
+
+Supercharge your terminal with AI: describe what you want, get a shell command
+that is correct for *your* system, confirm, run.
+
+## Why
+
+Small local models know what `find` or `sed` does, but not which options your
+copy has. GNU, BSD and BusyBox tools differ, so a command that's right on Linux
+can fail on a Mac. Thetaterm detects your OS and whether your tools are GNU,
+BSD or BusyBox, and gives the model the installed tool's `man` page. Every
+command is checked before you're asked to run it. It works with any model
+served over an OpenAI-compatible API, including ones on your own machine.
+
+## Requirements
+
+- macOS or Linux
+- [uv](https://docs.astral.sh/uv/getting-started/installation/). It installs
+  Python 3.13 or later for you if needed.
+- A model served over an OpenAI-compatible API. The default is `gemma4:e4b` on
+  [Ollama](https://ollama.com/download): `ollama pull gemma4:e4b`
+
+## Install
+
+```bash
+uv tool install thetaterm
+```
+
+## Quickstart
+
+```bash
+tterm -q "list files in this directory, largest first"
+```
+
+```
+$ ls -lS .
+Run it? [Y/n]:
+```
+
+New to it? Follow the [tutorial](https://github.com/thetaplex/thetaterm/blob/main/docs/tutorials/first-command.md).
+
+## Usage
+
+```bash
+tterm                                  # interactive
+tterm -q "find files modified in the last 2 days"
+tterm -m qwen2.5-coder:3b -q "replace foo with bar in notes.txt in place"   # another model
+tterm -y -q "show git status"          # run without confirming
+tterm --think -q "show the date 30 days from now"   # model reasons first, about 2x slower
+```
+
+> **Warning:** `-y` runs whatever the model writes, unreviewed. In interactive
+> mode that applies to every line you type. Commands pass a syntax check, not a
+> safety check.
+
+Commands that look like they reach outside the current directory (absolute,
+`~` or `..` paths, variables such as `$HOME`, `cd` home or back, or `sudo`) are shown in red and always ask first,
+defaulting to no, even with `-y`. This is a pattern match, not a sandbox. See
+the [safety model](https://github.com/thetaplex/thetaterm/blob/main/docs/explanation/safety.md).
+
+Settings (`THETATERM_MODEL`, `THETATERM_BASE_URL`, `THETATERM_API_KEY`) are
+read from the environment or `~/.config/thetaterm/.env`, never from a `.env`
+in the current directory. See the
+[command-line reference](https://github.com/thetaplex/thetaterm/blob/main/docs/reference/cli.md) and
+[how to use another model server](https://github.com/thetaplex/thetaterm/blob/main/docs/how-to/use-another-model-server.md).
+
+## Documentation
+
+- [Documentation index](https://github.com/thetaplex/thetaterm/blob/main/docs/README.md): tutorial, how-to guides, reference,
+  explanation and design decisions
+- [Contributing](https://github.com/thetaplex/thetaterm/blob/main/CONTRIBUTING.md): development setup, needs
+  [just](https://just.systems/man/en/packages.html)
+- [Security policy](https://github.com/thetaplex/thetaterm/blob/main/SECURITY.md)
+- [Changelog](https://github.com/thetaplex/thetaterm/blob/main/CHANGELOG.md)
+
+## License
+
+[Apache-2.0](https://github.com/thetaplex/thetaterm/blob/main/LICENSE)

thetaterm-0.1.1/README.md

@@ -0,0 +1,78 @@
+# Thetaterm
+
+Supercharge your terminal with AI: describe what you want, get a shell command
+that is correct for *your* system, confirm, run.
+
+## Why
+
+Small local models know what `find` or `sed` does, but not which options your
+copy has. GNU, BSD and BusyBox tools differ, so a command that's right on Linux
+can fail on a Mac. Thetaterm detects your OS and whether your tools are GNU,
+BSD or BusyBox, and gives the model the installed tool's `man` page. Every
+command is checked before you're asked to run it. It works with any model
+served over an OpenAI-compatible API, including ones on your own machine.
+
+## Requirements
+
+- macOS or Linux
+- [uv](https://docs.astral.sh/uv/getting-started/installation/). It installs
+  Python 3.13 or later for you if needed.
+- A model served over an OpenAI-compatible API. The default is `gemma4:e4b` on
+  [Ollama](https://ollama.com/download): `ollama pull gemma4:e4b`
+
+## Install
+
+```bash
+uv tool install thetaterm
+```
+
+## Quickstart
+
+```bash
+tterm -q "list files in this directory, largest first"
+```
+
+```
+$ ls -lS .
+Run it? [Y/n]:
+```
+
+New to it? Follow the [tutorial](https://github.com/thetaplex/thetaterm/blob/main/docs/tutorials/first-command.md).
+
+## Usage
+
+```bash
+tterm                                  # interactive
+tterm -q "find files modified in the last 2 days"
+tterm -m qwen2.5-coder:3b -q "replace foo with bar in notes.txt in place"   # another model
+tterm -y -q "show git status"          # run without confirming
+tterm --think -q "show the date 30 days from now"   # model reasons first, about 2x slower
+```
+
+> **Warning:** `-y` runs whatever the model writes, unreviewed. In interactive
+> mode that applies to every line you type. Commands pass a syntax check, not a
+> safety check.
+
+Commands that look like they reach outside the current directory (absolute,
+`~` or `..` paths, variables such as `$HOME`, `cd` home or back, or `sudo`) are shown in red and always ask first,
+defaulting to no, even with `-y`. This is a pattern match, not a sandbox. See
+the [safety model](https://github.com/thetaplex/thetaterm/blob/main/docs/explanation/safety.md).
+
+Settings (`THETATERM_MODEL`, `THETATERM_BASE_URL`, `THETATERM_API_KEY`) are
+read from the environment or `~/.config/thetaterm/.env`, never from a `.env`
+in the current directory. See the
+[command-line reference](https://github.com/thetaplex/thetaterm/blob/main/docs/reference/cli.md) and
+[how to use another model server](https://github.com/thetaplex/thetaterm/blob/main/docs/how-to/use-another-model-server.md).
+
+## Documentation
+
+- [Documentation index](https://github.com/thetaplex/thetaterm/blob/main/docs/README.md): tutorial, how-to guides, reference,
+  explanation and design decisions
+- [Contributing](https://github.com/thetaplex/thetaterm/blob/main/CONTRIBUTING.md): development setup, needs
+  [just](https://just.systems/man/en/packages.html)
+- [Security policy](https://github.com/thetaplex/thetaterm/blob/main/SECURITY.md)
+- [Changelog](https://github.com/thetaplex/thetaterm/blob/main/CHANGELOG.md)
+
+## License
+
+[Apache-2.0](https://github.com/thetaplex/thetaterm/blob/main/LICENSE)

thetaterm-0.1.1/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "thetaterm"
+version = "0.1.1"
+description = "Supercharge your terminal with AI"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = [
+    "LICENSE",
+    "NOTICE",
+]
+requires-python = ">=3.13"
+keywords = [
+    "shell",
+    "terminal",
+    "cli",
+    "llm",
+    "ollama",
+    "natural-language",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Shells",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "python-dotenv>=1.2.3",
+    "rich>=14.1.0",
+    "typer>=0.17.3",
+]
+
+[[project.authors]]
+name = "ThetaPlex"
+email = "support@thetaplex.com"
+
+[project.urls]
+Repository = "https://github.com/thetaplex/thetaterm"
+Documentation = "https://github.com/thetaplex/thetaterm/tree/main/docs"
+Issues = "https://github.com/thetaplex/thetaterm/issues"
+Changelog = "https://github.com/thetaplex/thetaterm/blob/main/CHANGELOG.md"
+
+[project.scripts]
+tterm = "thetaterm.cli:app"
+
+[dependency-groups]
+dev = [
+    "opentelemetry-exporter-otlp-proto-http>=1.45.0",
+    "opentelemetry-sdk>=1.45.0",
+    "pytest>=8.4.1",
+    "ruff>=0.16.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.8,<0.10"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""

thetaterm-0.1.1/pyproject.toml.orig

@@ -0,0 +1,54 @@
+[project]
+name = "thetaterm"
+version = "0.1.1"
+description = "Supercharge your terminal with AI"
+readme = "README.md"
+authors = [{ name = "ThetaPlex", email = "support@thetaplex.com" }]
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.13"
+keywords = ["shell", "terminal", "cli", "llm", "ollama", "natural-language"]
+# no License :: classifier: license (SPDX) replaces it, and PyPI rejects both
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Shells",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "python-dotenv>=1.2.3",
+    "rich>=14.1.0",
+    "typer>=0.17.3",
+]
+
+[dependency-groups]
+dev = [
+    "opentelemetry-exporter-otlp-proto-http>=1.45.0",
+    "opentelemetry-sdk>=1.45.0",
+    "pytest>=8.4.1",
+    "ruff>=0.16.9",
+]
+
+[project.urls]
+Repository = "https://github.com/thetaplex/thetaterm"
+Documentation = "https://github.com/thetaplex/thetaterm/tree/main/docs"
+Issues = "https://github.com/thetaplex/thetaterm/issues"
+Changelog = "https://github.com/thetaplex/thetaterm/blob/main/CHANGELOG.md"
+
+[project.scripts]
+tterm = "thetaterm.cli:app"
+
+
+[build-system]
+requires = ["uv_build>=0.8,<0.10"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""

thetaterm-0.1.1/thetaterm/agent.py

@@ -0,0 +1,331 @@
+"""Turn natural language into a shell command using the OS's own docs.
+
+Small models can't memorise the differences between GNU, BSD and BusyBox
+userlands, so we don't ask them to: the model suggests commands, the machine
+says which are installed, and the man page of the chosen one goes into the
+prompt. The model only has to read and fill in.
+"""
+
+import json
+import math
+import os
+import platform
+import re
+import shlex
+import shutil
+import subprocess
+import urllib.error
+import urllib.request
+
+# problem() and outside() read commands as sh words, so only shells that parse like sh
+POSIX_SHELLS = {"sh", "bash", "zsh", "ksh", "dash"}
+
+
+def user_shell() -> str:
+    """The login shell if it parses like sh, else bash, else /bin/sh."""
+    login = os.environ.get("SHELL", "")
+    if os.path.basename(login) in POSIX_SHELLS and shutil.which(login):
+        return login
+    return shutil.which("bash") or "/bin/sh"
+
+
+SHELL = user_shell()
+_STOPWORDS = (
+    "a an the to of in on for from with and or all any my me i this that these those "
+    "is are be it its by as at into using use how what which show get make do"
+)
+STOPWORDS = set(_STOPWORDS.split())
+# `!` negates a pipeline in command position; elsewhere (find ! -name) it is an argument
+PREFIXES = {"sudo", "env", "time", "nohup", "command", "!"}
+MAX_REFERENCE_CHARS = 3500
+RETRIES = 2
+# devices that hold no files; anything else under /dev (disks) counts as outside
+SAFE_DEVICE = re.compile(r"/dev/(null|zero|u?random|tty|std(in|out|err)|fd/\d+)")
+# variables that can't name a directory
+SAFE_VARIABLES = {"PWD", "USER", "LOGNAME", "UID", "RANDOM", "IFS"}
+
+
+def sh(args: list[str], timeout: int = 10) -> subprocess.CompletedProcess:
+    env = os.environ | {"PAGER": "cat", "MANPAGER": "cat", "MANWIDTH": "100"}
+    try:
+        return subprocess.run(
+            args, capture_output=True, text=True, timeout=timeout, env=env, check=False
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return subprocess.CompletedProcess(args, 1, "", str(e))
+
+
+def environment() -> str:
+    """One line describing the OS and which userland flavour its tools are."""
+    system = platform.system()
+    if system == "Darwin":
+        name = f"macOS {platform.mac_ver()[0]}"
+    elif system == "Linux":
+        try:
+            name = platform.freedesktop_os_release().get("PRETTY_NAME", "Linux")
+        except OSError:
+            name = "Linux"
+    else:
+        name = f"{system} {platform.release()}"
+
+    ls = shutil.which("ls") or ""
+    if os.path.realpath(ls).endswith("busybox"):
+        userland = "BusyBox"
+    elif "GNU" in sh(["ls", "--version"]).stdout:
+        userland = "GNU coreutils"
+    else:
+        userland = "BSD"
+    return f"{name}, {userland} userland, {os.path.basename(SHELL)} shell"
+
+
+def keywords(query: str) -> list[str]:
+    words = re.findall(r"[a-z0-9][a-z0-9._+-]*", query.lower())
+    # ponytail: crude plural stripping, a real stemmer if excerpts miss too much
+    return [
+        w[:-1] if len(w) > 3 and w.endswith("s") else w
+        for w in words
+        if w not in STOPWORDS
+    ]
+
+
+def reference(command: str, query: str) -> str:
+    """The parts of a command's man page relevant to the query.
+
+    Never `command --help`: a program that doesn't honour it would run before
+    the user agreed to anything (ADR 0005).
+    """
+    text = re.sub(r".\x08", "", sh(["man", command]).stdout)  # strip overstrike bold
+    return excerpt(text, query)
+
+
+def entries(text: str) -> list[tuple[int, str]]:
+    """Split docs into (first line number, text) paragraphs and option entries."""
+    found, current, start, indent, blank = [], [], 0, 0, False
+    for n, line in enumerate(text.splitlines()):
+        line = line.rstrip()
+        body = line.lstrip()
+        if not body:
+            blank = True
+            continue
+        depth = len(line) - len(body)
+        # an option at or left of the entry's own indent starts a new one, even
+        # without a blank line between (--help output rarely has them); after a
+        # blank line only text indented under an option continues it (-type's list)
+        under_option = current[:1] and current[0].lstrip().startswith("-")
+        if current and (
+            (blank and not (under_option and depth > indent))
+            or (body.startswith("-") and depth <= indent)
+        ):
+            found.append((start, "\n".join(current)))
+            current = []
+        if not current:
+            start, indent = n, depth
+        current.append(line)
+        blank = False
+    if current:
+        found.append((start, "\n".join(current)))
+    return found
+
+
+def excerpt(text: str, query: str) -> str:
+    """Whole entries that best match the query, rare words counting most."""
+    chunks = entries(text)
+    words = set(keywords(query))
+    matches = [{w for w in words if w in chunk.lower()} for _, chunk in chunks]
+    df = {w: sum(w in m for m in matches) for w in words}
+    idf = {w: math.log(len(chunks) / n) for w, n in df.items() if n}
+
+    def score(i: int) -> float:
+        if chunks[i][0] < 20:  # NAME + SYNOPSIS
+            return math.inf
+        return sum(idf[w] for w in matches[i])
+
+    keep, used = set(), 0
+    # stable sort: ties go to whatever comes first on the page
+    for i in sorted(range(len(chunks)), key=score, reverse=True):
+        size = len(chunks[i][1]) + 1
+        if score(i) and used + size <= MAX_REFERENCE_CHARS:
+            keep.add(i)
+            used += size
+    return "\n".join(chunks[i][1] for i in sorted(keep))
+
+
+def clean(response: str) -> str:
+    """Pull the bare command out of whatever the model wrapped it in."""
+    # a fenced block beats any prose around it
+    fenced = re.search(r"```\w*\n(.*?)```", response, re.DOTALL)
+    text = fenced[1] if fenced else re.sub(r"```\w*", "", response).strip()
+    line = next((line.strip() for line in text.splitlines() if line.strip()), "")
+    # some models echo the prompt's "Command:" label
+    line = re.sub(r"^command:\s*", "", line, flags=re.IGNORECASE).strip("`")
+    for prefix in ("$ ", "# ", "> "):
+        line = line.removeprefix(prefix)
+    return line.strip()
+
+
+def tokens(command: str) -> list[str]:
+    """Shell words and operators; raises ValueError on unbalanced quotes."""
+    lexer = shlex.shlex(command, posix=True, punctuation_chars=True)
+    lexer.whitespace_split = True
+    return list(lexer)
+
+
+def outside(command: str) -> str | None:
+    """Why this command may reach beyond the current directory, or None.
+
+    ponytail: pattern match on the words, catches the model's honest mistakes, not
+    obfuscation (`cat $(printf '\\x2f')etc`); a real sandbox if that matters.
+    """
+    words = tokens(command)
+    for i, token in enumerate(words):
+        # --output=/tmp/x, of=/dev/sda, -C/tmp
+        path = re.sub(r"^-[A-Za-z]", "", token.split("=", 1)[-1])
+        if token == "sudo":
+            return "runs as root"
+        # bare `cd` goes home, `cd -` and `popd` go back to an earlier directory
+        target = words[i + 1] if i + 1 < len(words) else ";"
+        if token in {"cd", "pushd", "popd"} and target in {
+            "-",
+            ";",
+            "&&",
+            "||",
+            "&",
+            ")",
+        }:
+            return f"{token} leaves for the home or previous directory"
+        if path.startswith("~"):
+            return f"home path {token}"
+        if path.startswith("/") and not SAFE_DEVICE.fullmatch(path):
+            return f"absolute path {token}"
+        if ".." in path.split("/"):
+            return f"parent path {token}"
+    # any variable may hold a path; single quotes don't expand, loop and read
+    # variables are the command's own
+    unquoted = re.sub(r"'[^']*'", "", command)
+    own = set(re.findall(r"\bfor\s+(\w+)\s+in\b", unquoted))
+    own |= set(re.findall(r"\bread\s+(?:-\w+\s+)*(\w+)", unquoted))
+    own |= set(re.findall(r"(?:^|[\s;&|(])([A-Za-z_]\w*)=", unquoted))
+    for name in re.findall(r"\$\{?([A-Za-z_]\w*)", unquoted):
+        if name not in own | SAFE_VARIABLES:
+            return f"uses ${name}"
+    return None
+
+
+def problem(command: str) -> str | None:
+    """Why this command would fail before it even runs, or None."""
+    if not command:
+        return "empty command"
+    # stderr, not the exit status: zsh -n returns 1 for a valid `! cmd`
+    r = sh([SHELL, "-n", "-c", command])
+    if r.returncode and r.stderr.strip():
+        return r.stderr.strip()
+    try:
+        # shlex unquotes find's `\;` into a bare `;`, which would read as a separator
+        words = tokens(re.sub(r"\\;|';'|\";\"", "_", command))
+    except ValueError as e:
+        return str(e)
+    at_command = True
+    for token in words:
+        if token in {"|", "||", "&&", ";", "&", "(", "{"}:
+            at_command = True
+        elif at_command:
+            if re.match(r"\w+=", token) or token in PREFIXES:
+                continue
+            if sh([SHELL, "-c", f"command -v {shlex.quote(token)}"]).returncode:
+                return f"{token}: command not found"
+            at_command = False
+    return None
+
+
+class Agent:
+    """Talks to any OpenAI-compatible chat endpoint (Ollama, llama.cpp, vLLM, ...)."""
+
+    def __init__(
+        self,
+        model: str,
+        base_url: str,
+        api_key: str | None = None,
+        thinking: bool = False,
+    ):
+        self.model = model
+        self.url = base_url.rstrip("/") + "/chat/completions"
+        self.headers = {"Content-Type": "application/json"}
+        if api_key:
+            self.headers["Authorization"] = f"Bearer {api_key}"
+        self.env = environment()
+        # Thinking models reason for minutes over a man page to write one command.
+        # Dropped if the server rejects it.
+        self.thinking = thinking
+        self.thinking_off = {} if thinking else {"reasoning_effort": "none"}
+
+    def ask(self, prompt: str, max_tokens: int | None = None) -> str:
+        body = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0,
+        } | self.thinking_off
+        # reasoning counts against max_tokens, so a cap would cut thinking short
+        if max_tokens and not self.thinking:
+            body["max_tokens"] = max_tokens
+        request = urllib.request.Request(
+            self.url, json.dumps(body).encode(), self.headers
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=300) as r:
+                reply = json.load(r)
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode()[:200]
+            if e.code == 400 and self.thinking_off and "reasoning" in detail:
+                self.thinking_off = {}
+                return self.ask(prompt, max_tokens)
+            raise RuntimeError(f"{self.url}: {e.code} {detail}")
+        except OSError as e:
+            raise RuntimeError(f"cannot reach {self.url}: {getattr(e, 'reason', e)}")
+        except ValueError:
+            raise RuntimeError(f"{self.url}: reply is not JSON") from None
+        try:
+            return reply["choices"][0]["message"]["content"] or ""
+        except (KeyError, IndexError, TypeError):
+            # some servers answer 200 with {"error": ...}
+            raise RuntimeError(
+                f"{self.url}: unexpected reply {json.dumps(reply)[:200]}"
+            ) from None
+
+    def choose(self, query: str) -> str | None:
+        """The main command for the task: the model suggests, the OS confirms."""
+        answer = self.ask(
+            f"System: {self.env}\nTask: {query}\n"
+            "Which commands can do this? List up to 5 command names only, one per line, best first.",
+            # some models repeat the last name until the context runs out
+            max_tokens=60,
+        )
+        # one name per line or comma: "1. `ifconfig` - shows ..." -> ifconfig
+        for item in re.split(r"[\n,]", answer):
+            name = next(iter(re.findall(r"[A-Za-z][\w.+-]*", item)), None)
+            if name and shutil.which(name):
+                return name
+        return None
+
+    def generate(self, query: str) -> str:
+        """Best command for the query; raises RuntimeError if none passes checks."""
+        prompt = f"System: {self.env}\n"
+        # a thinking model works out the platform's flags itself; the extra
+        # round trip and man page only slow it down (evals: 49/50 vs 48/50)
+        chosen = None if self.thinking else self.choose(query)
+        if chosen:
+            ref = reference(chosen, query)
+            prompt += f"\nReference for `{chosen}` on this system:\n{ref}\n"
+        prompt += (
+            f"\nTask: {query}\nWrite one {os.path.basename(SHELL)} command for this system. "
+            "Use real paths, never placeholders like /path/to; if the task names no location, use the current directory (.). "
+            "Reply with the command only.\n"
+        )
+
+        attempt = prompt
+        for _ in range(RETRIES + 1):
+            command = clean(self.ask(attempt + "Command:"))
+            error = problem(command)
+            if error is None:
+                return command
+            attempt = f"{prompt}\nThe command `{command}` fails: {error}\nWrite a corrected command.\n"
+        raise RuntimeError(f"no working command found (last: `{command}`: {error})")

thetaterm-0.1.1/thetaterm/cli.py

@@ -0,0 +1,104 @@
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+from urllib.parse import urlsplit
+
+import typer
+from dotenv import load_dotenv
+from rich.console import Console
+
+from thetaterm.agent import SHELL, Agent, outside
+
+# Per-user config only: a .env in the working directory could be a cloned repo's,
+# and would get to pick the endpoint our API key is sent to.
+CONFIG = (
+    Path(os.getenv("XDG_CONFIG_HOME") or Path.home() / ".config") / "thetaterm" / ".env"
+)
+load_dotenv(CONFIG)
+
+app = typer.Typer()
+console = Console()
+
+DEFAULT_MODEL = "gemma4:e4b"
+DEFAULT_BASE_URL = "http://localhost:11434/v1"  # Ollama
+LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def process_query(agent: Agent, query: str, yes: bool) -> int:
+    """Generate a command for the query, confirm it, run it. Returns its exit code."""
+    try:
+        with console.status("thinking…"):
+            command = agent.generate(query)
+    except RuntimeError as e:
+        console.print(str(e), style="red", markup=False)
+        return 1
+    except KeyboardInterrupt:  # back to the > prompt, no traceback
+        return 130
+
+    # markup=False: `grep [abc] f` must show its brackets, and `[conceal]` mustn't
+    # hide words, or the command you approve isn't the one that runs
+    console.print(f"$ {command}", style="cyan", markup=False)
+    reason = outside(command)
+    if reason:
+        # never auto-run these, even with -y, and default to no
+        console.print(
+            f"leaves the current directory: {reason}", style="red", markup=False
+        )
+    if (reason or not yes) and not typer.confirm("Run it?", default=not reason):
+        return 0
+    try:
+        return subprocess.run(
+            command, shell=True, executable=SHELL, check=False
+        ).returncode
+    except KeyboardInterrupt:  # Ctrl-C stops the command, not the session
+        return 130
+
+
+@app.command()
+def tterm(
+    query: Annotated[
+        str | None,
+        typer.Option(
+            "--query", "-q", help="The request; without it, start interactive mode"
+        ),
+    ] = None,
+    model: Annotated[
+        str, typer.Option("--model", "-m", envvar="THETATERM_MODEL")
+    ] = DEFAULT_MODEL,
+    yes: Annotated[
+        bool, typer.Option("--yes", "-y", help="Run without asking")
+    ] = False,
+    think: Annotated[
+        bool, typer.Option("--think", help="Let the model reason first: slower")
+    ] = False,
+):
+    """
+    Describe a task in plain words, get a shell command for this system, confirm, run it.
+    """
+    base_url = os.getenv("THETATERM_BASE_URL") or DEFAULT_BASE_URL
+    api_key = os.getenv("THETATERM_API_KEY")
+    url = urlsplit(base_url)
+    if api_key and url.scheme == "http" and url.hostname not in LOCAL_HOSTS:
+        console.print(
+            f"[yellow]warning: API key sent unencrypted to {base_url}[/yellow]"
+        )
+    agent = Agent(model, base_url, api_key, think)
+    if query is not None:
+        sys.exit(process_query(agent, query, yes))
+
+    console.print(f"[bold cyan]Thetaterm[/bold cyan] · {model} · {agent.env}")
+    console.print("[dim]Describe what you want. Ctrl-D to exit.[/dim]")
+    while True:
+        try:
+            line = input("\n> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            console.print()
+            return
+        if line:
+            process_query(agent, line, yes)
+
+
+if __name__ == "__main__":
+    app()