betterborg 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. betterborg-0.1.0/LICENSE +21 -0
  2. betterborg-0.1.0/NOTICE +7 -0
  3. betterborg-0.1.0/PKG-INFO +106 -0
  4. betterborg-0.1.0/README.md +83 -0
  5. betterborg-0.1.0/pyproject.toml +87 -0
  6. betterborg-0.1.0/setup.cfg +4 -0
  7. betterborg-0.1.0/src/betterborg.egg-info/PKG-INFO +106 -0
  8. betterborg-0.1.0/src/betterborg.egg-info/SOURCES.txt +166 -0
  9. betterborg-0.1.0/src/betterborg.egg-info/dependency_links.txt +1 -0
  10. betterborg-0.1.0/src/betterborg.egg-info/entry_points.txt +2 -0
  11. betterborg-0.1.0/src/betterborg.egg-info/requires.txt +2 -0
  12. betterborg-0.1.0/src/betterborg.egg-info/top_level.txt +1 -0
  13. betterborg-0.1.0/src/betterborg_cli/__init__.py +3 -0
  14. betterborg-0.1.0/src/betterborg_cli/__main__.py +8 -0
  15. betterborg-0.1.0/src/betterborg_cli/agent_runtime/__init__.py +125 -0
  16. betterborg-0.1.0/src/betterborg_cli/agent_runtime/anthropic.py +431 -0
  17. betterborg-0.1.0/src/betterborg_cli/agent_runtime/api_adapter.py +232 -0
  18. betterborg-0.1.0/src/betterborg_cli/agent_runtime/api_tools.py +562 -0
  19. betterborg-0.1.0/src/betterborg_cli/agent_runtime/base.py +211 -0
  20. betterborg-0.1.0/src/betterborg_cli/agent_runtime/claude.py +302 -0
  21. betterborg-0.1.0/src/betterborg_cli/agent_runtime/codex.py +492 -0
  22. betterborg-0.1.0/src/betterborg_cli/agent_runtime/mock.py +210 -0
  23. betterborg-0.1.0/src/betterborg_cli/agent_runtime/native_cli.py +342 -0
  24. betterborg-0.1.0/src/betterborg_cli/agent_runtime/openai.py +503 -0
  25. betterborg-0.1.0/src/betterborg_cli/agent_runtime/pricing.py +97 -0
  26. betterborg-0.1.0/src/betterborg_cli/agent_runtime/process.py +103 -0
  27. betterborg-0.1.0/src/betterborg_cli/agent_runtime/retry.py +109 -0
  28. betterborg-0.1.0/src/betterborg_cli/agent_runtime/selection.py +385 -0
  29. betterborg-0.1.0/src/betterborg_cli/agent_runtime/structured.py +387 -0
  30. betterborg-0.1.0/src/betterborg_cli/claude_plugin.py +576 -0
  31. betterborg-0.1.0/src/betterborg_cli/claude_plugin_bundle/__init__.py +1 -0
  32. betterborg-0.1.0/src/betterborg_cli/claude_plugin_bundle/marketplace/.claude-plugin/marketplace.json +14 -0
  33. betterborg-0.1.0/src/betterborg_cli/claude_plugin_bundle/marketplace/plugins/borg/.claude-plugin/plugin.json +11 -0
  34. betterborg-0.1.0/src/betterborg_cli/claude_plugin_bundle/marketplace/plugins/borg/.mcp.json +8 -0
  35. betterborg-0.1.0/src/betterborg_cli/claude_plugin_bundle/marketplace/plugins/borg/commands/borg.md +10 -0
  36. betterborg-0.1.0/src/betterborg_cli/claude_plugin_bundle/marketplace/plugins/borg/skills/orchestrate/SKILL.md +19 -0
  37. betterborg-0.1.0/src/betterborg_cli/cli.py +1465 -0
  38. betterborg-0.1.0/src/betterborg_cli/codex_plugin.py +570 -0
  39. betterborg-0.1.0/src/betterborg_cli/codex_plugin_bundle/__init__.py +1 -0
  40. betterborg-0.1.0/src/betterborg_cli/codex_plugin_bundle/marketplace/.agents/plugins/marketplace.json +21 -0
  41. betterborg-0.1.0/src/betterborg_cli/codex_plugin_bundle/marketplace/plugins/borg/.codex-plugin/plugin.json +28 -0
  42. betterborg-0.1.0/src/betterborg_cli/codex_plugin_bundle/marketplace/plugins/borg/.mcp.json +6 -0
  43. betterborg-0.1.0/src/betterborg_cli/codex_plugin_bundle/marketplace/plugins/borg/skills/orchestrate/SKILL.md +19 -0
  44. betterborg-0.1.0/src/betterborg_cli/execution_estimate.py +462 -0
  45. betterborg-0.1.0/src/betterborg_cli/host_execution/__init__.py +132 -0
  46. betterborg-0.1.0/src/betterborg_cli/host_execution/_agent_phase.py +318 -0
  47. betterborg-0.1.0/src/betterborg_cli/host_execution/_locking.py +59 -0
  48. betterborg-0.1.0/src/betterborg_cli/host_execution/coding.py +503 -0
  49. betterborg-0.1.0/src/betterborg_cli/host_execution/compose.py +1145 -0
  50. betterborg-0.1.0/src/betterborg_cli/host_execution/environment.py +1142 -0
  51. betterborg-0.1.0/src/betterborg_cli/host_execution/git.py +512 -0
  52. betterborg-0.1.0/src/betterborg_cli/host_execution/guard.py +155 -0
  53. betterborg-0.1.0/src/betterborg_cli/host_execution/merge.py +1159 -0
  54. betterborg-0.1.0/src/betterborg_cli/host_execution/preflight.py +1358 -0
  55. betterborg-0.1.0/src/betterborg_cli/host_execution/review.py +908 -0
  56. betterborg-0.1.0/src/betterborg_cli/host_execution/sanity.py +572 -0
  57. betterborg-0.1.0/src/betterborg_cli/host_execution/scheduler.py +374 -0
  58. betterborg-0.1.0/src/betterborg_cli/host_execution/service.py +573 -0
  59. betterborg-0.1.0/src/betterborg_cli/host_execution/worktrees.py +293 -0
  60. betterborg-0.1.0/src/betterborg_cli/mcp_server.py +1237 -0
  61. betterborg-0.1.0/src/betterborg_cli/onboarding.py +203 -0
  62. betterborg-0.1.0/src/betterborg_cli/planning/__init__.py +121 -0
  63. betterborg-0.1.0/src/betterborg_cli/planning/architect.py +611 -0
  64. betterborg-0.1.0/src/betterborg_cli/planning/plan_contracts.py +586 -0
  65. betterborg-0.1.0/src/betterborg_cli/planning/pm.py +727 -0
  66. betterborg-0.1.0/src/betterborg_cli/planning/supervisor.py +639 -0
  67. betterborg-0.1.0/src/betterborg_cli/planning/task_publication.py +449 -0
  68. betterborg-0.1.0/src/betterborg_cli/planning/task_render.py +63 -0
  69. betterborg-0.1.0/src/betterborg_cli/planning/task_validation.py +807 -0
  70. betterborg-0.1.0/src/betterborg_cli/planning/tech_lead.py +401 -0
  71. betterborg-0.1.0/src/betterborg_cli/planning/turns.py +298 -0
  72. betterborg-0.1.0/src/betterborg_cli/planning/worktree.py +433 -0
  73. betterborg-0.1.0/src/betterborg_cli/plugin_activation.py +221 -0
  74. betterborg-0.1.0/src/betterborg_cli/plugin_installation.py +337 -0
  75. betterborg-0.1.0/src/betterborg_cli/plugins.py +149 -0
  76. betterborg-0.1.0/src/betterborg_cli/prd_session.py +406 -0
  77. betterborg-0.1.0/src/betterborg_cli/repo_analysis/__init__.py +97 -0
  78. betterborg-0.1.0/src/betterborg_cli/repo_analysis/analyzer.py +697 -0
  79. betterborg-0.1.0/src/betterborg_cli/repo_analysis/discovery.py +631 -0
  80. betterborg-0.1.0/src/betterborg_cli/repo_analysis/improvement_prds.py +298 -0
  81. betterborg-0.1.0/src/betterborg_cli/repo_analysis/prompts_manager.py +367 -0
  82. betterborg-0.1.0/src/betterborg_cli/repo_analysis/reporting.py +618 -0
  83. betterborg-0.1.0/src/betterborg_cli/repo_analysis/scoring.py +380 -0
  84. betterborg-0.1.0/src/betterborg_cli/repo_analysis/text_rendering.py +42 -0
  85. betterborg-0.1.0/src/betterborg_cli/repo_paths.py +116 -0
  86. betterborg-0.1.0/src/betterborg_cli/repository_config.py +240 -0
  87. betterborg-0.1.0/src/betterborg_cli/repository_files.py +111 -0
  88. betterborg-0.1.0/src/betterborg_cli/repository_service.py +340 -0
  89. betterborg-0.1.0/src/betterborg_cli/store/__init__.py +91 -0
  90. betterborg-0.1.0/src/betterborg_cli/store/migrations/001_initial.sql +30 -0
  91. betterborg-0.1.0/src/betterborg_cli/store/migrations/002_analysis_history.sql +91 -0
  92. betterborg-0.1.0/src/betterborg_cli/store/migrations/003_borg_prd_sessions.sql +48 -0
  93. betterborg-0.1.0/src/betterborg_cli/store/migrations/004_planning_state.sql +159 -0
  94. betterborg-0.1.0/src/betterborg_cli/store/migrations/005_task_generations.sql +234 -0
  95. betterborg-0.1.0/src/betterborg_cli/store/migrations/006_execution_ownership.sql +312 -0
  96. betterborg-0.1.0/src/betterborg_cli/store/migrations/007_open_execution_attempts.sql +141 -0
  97. betterborg-0.1.0/src/betterborg_cli/store/migrations/008_execution_attempt_finalization.sql +11 -0
  98. betterborg-0.1.0/src/betterborg_cli/store/migrations/009_execution_incarnations.sql +80 -0
  99. betterborg-0.1.0/src/betterborg_cli/store/migrations/010_run_environment_attempts.sql +116 -0
  100. betterborg-0.1.0/src/betterborg_cli/store/migrations/011_execution_decisions.sql +57 -0
  101. betterborg-0.1.0/src/betterborg_cli/store/migrations/__init__.py +1 -0
  102. betterborg-0.1.0/src/betterborg_cli/store/models.py +1033 -0
  103. betterborg-0.1.0/src/betterborg_cli/store/sqlite.py +4094 -0
  104. betterborg-0.1.0/src/betterborg_cli/workflow_service.py +347 -0
  105. betterborg-0.1.0/src/betterborg_cli/workspace_trust.py +196 -0
  106. betterborg-0.1.0/tests/test_adapter_harness.py +322 -0
  107. betterborg-0.1.0/tests/test_agent_api_tools.py +245 -0
  108. betterborg-0.1.0/tests/test_agent_process.py +136 -0
  109. betterborg-0.1.0/tests/test_agent_runtime.py +234 -0
  110. betterborg-0.1.0/tests/test_agent_selection.py +552 -0
  111. betterborg-0.1.0/tests/test_anthropic_adapter.py +230 -0
  112. betterborg-0.1.0/tests/test_api_adapter_contract.py +467 -0
  113. betterborg-0.1.0/tests/test_binary_release.py +229 -0
  114. betterborg-0.1.0/tests/test_claude_adapter.py +376 -0
  115. betterborg-0.1.0/tests/test_claude_plugin.py +678 -0
  116. betterborg-0.1.0/tests/test_cli.py +326 -0
  117. betterborg-0.1.0/tests/test_cli_execute.py +1157 -0
  118. betterborg-0.1.0/tests/test_cli_plan_approval.py +384 -0
  119. betterborg-0.1.0/tests/test_cli_planning.py +566 -0
  120. betterborg-0.1.0/tests/test_cli_tasks.py +416 -0
  121. betterborg-0.1.0/tests/test_codex_adapter.py +724 -0
  122. betterborg-0.1.0/tests/test_codex_plugin.py +461 -0
  123. betterborg-0.1.0/tests/test_distribution.py +340 -0
  124. betterborg-0.1.0/tests/test_execution_estimate.py +321 -0
  125. betterborg-0.1.0/tests/test_execution_preflight.py +1861 -0
  126. betterborg-0.1.0/tests/test_final_release.py +441 -0
  127. betterborg-0.1.0/tests/test_foundation_fixtures.py +25 -0
  128. betterborg-0.1.0/tests/test_github_release_verification.py +433 -0
  129. betterborg-0.1.0/tests/test_host_coding.py +875 -0
  130. betterborg-0.1.0/tests/test_host_execution_service.py +2861 -0
  131. betterborg-0.1.0/tests/test_host_merge.py +644 -0
  132. betterborg-0.1.0/tests/test_host_preflight.py +976 -0
  133. betterborg-0.1.0/tests/test_host_sanity.py +446 -0
  134. betterborg-0.1.0/tests/test_host_scheduler.py +399 -0
  135. betterborg-0.1.0/tests/test_host_worktrees.py +491 -0
  136. betterborg-0.1.0/tests/test_install_script.py +286 -0
  137. betterborg-0.1.0/tests/test_mcp_server.py +1221 -0
  138. betterborg-0.1.0/tests/test_npm_release.py +101 -0
  139. betterborg-0.1.0/tests/test_onboarding.py +216 -0
  140. betterborg-0.1.0/tests/test_openai_adapter.py +235 -0
  141. betterborg-0.1.0/tests/test_planning_architect.py +783 -0
  142. betterborg-0.1.0/tests/test_planning_plan_contracts.py +499 -0
  143. betterborg-0.1.0/tests/test_planning_task_publication.py +253 -0
  144. betterborg-0.1.0/tests/test_planning_task_validation.py +1696 -0
  145. betterborg-0.1.0/tests/test_planning_tech_lead.py +410 -0
  146. betterborg-0.1.0/tests/test_planning_worktree.py +330 -0
  147. betterborg-0.1.0/tests/test_plugin_activation.py +146 -0
  148. betterborg-0.1.0/tests/test_plugins.py +248 -0
  149. betterborg-0.1.0/tests/test_prd_session.py +462 -0
  150. betterborg-0.1.0/tests/test_public_installations.py +142 -0
  151. betterborg-0.1.0/tests/test_public_tree.py +154 -0
  152. betterborg-0.1.0/tests/test_release_workflow.py +350 -0
  153. betterborg-0.1.0/tests/test_repo_analysis_analyzer.py +398 -0
  154. betterborg-0.1.0/tests/test_repo_analysis_discovery.py +350 -0
  155. betterborg-0.1.0/tests/test_repo_analysis_improvement_prds.py +432 -0
  156. betterborg-0.1.0/tests/test_repo_analysis_prompts_manager.py +479 -0
  157. betterborg-0.1.0/tests/test_repo_analysis_reporting.py +814 -0
  158. betterborg-0.1.0/tests/test_repo_analysis_scoring.py +288 -0
  159. betterborg-0.1.0/tests/test_repo_paths.py +94 -0
  160. betterborg-0.1.0/tests/test_repository_config.py +162 -0
  161. betterborg-0.1.0/tests/test_repository_files.py +58 -0
  162. betterborg-0.1.0/tests/test_repository_initialization.py +504 -0
  163. betterborg-0.1.0/tests/test_store.py +267 -0
  164. betterborg-0.1.0/tests/test_store_execution.py +1888 -0
  165. betterborg-0.1.0/tests/test_store_execution_decisions.py +240 -0
  166. betterborg-0.1.0/tests/test_store_planning.py +281 -0
  167. betterborg-0.1.0/tests/test_store_task_generations.py +321 -0
  168. betterborg-0.1.0/tests/test_workspace_trust.py +153 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 BetterBorg
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,7 @@
1
+ BetterBorg CLI
2
+ Copyright 2026 BetterBorg
3
+
4
+ This product includes software developed by BetterBorg
5
+ (https://github.com/betterborg).
6
+
7
+ BetterBorg CLI is distributed under the MIT License. See LICENSE.
@@ -0,0 +1,106 @@
1
+ Metadata-Version: 2.4
2
+ Name: betterborg
3
+ Version: 0.1.0
4
+ Summary: The open source BetterBorg command-line interface
5
+ Author: BetterBorg
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/betterborg/betterborg-cli
8
+ Project-URL: Repository, https://github.com/betterborg/betterborg-cli
9
+ Project-URL: Issues, https://github.com/betterborg/betterborg-cli/issues
10
+ Classifier: Development Status :: 2 - Pre-Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Requires-Python: >=3.11
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ License-File: NOTICE
20
+ Requires-Dist: click<9,>=8.1
21
+ Requires-Dist: mcp<2,>=1.12
22
+ Dynamic: license-file
23
+
24
+ # BetterBorg CLI
25
+
26
+ [![PyPI](https://img.shields.io/pypi/v/betterborg.svg?style=flat-square)](https://pypi.org/project/betterborg/)
27
+ [![npm](https://img.shields.io/npm/v/@betterborg/cli.svg?style=flat-square)](https://www.npmjs.com/package/@betterborg/cli)
28
+ ![Python](https://img.shields.io/badge/Python-3.11%2B-brightgreen?style=flat-square)
29
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
30
+
31
+ BetterBorg is an AI engineering team for substantial software projects, not a chat window that makes an isolated edit. You give it a task or a PRD; agents investigate your real code, write a reviewed technical plan, decompose it into a dependency graph of tasks, and implement them — each in its own isolated Git worktree. You approve the plan before anything is decomposed, and the estimate before anything runs. It works locally, on your own Claude Code or Codex subscription.
32
+
33
+ > [!NOTE]
34
+ > Pre-alpha. Interfaces may change between releases.
35
+
36
+ ## Get started
37
+
38
+ 1. Install the CLI:
39
+
40
+ ```bash
41
+ pip install betterborg
42
+ ```
43
+
44
+ Or install the standalone release binary for Darwin or Linux, which needs
45
+ no Python toolchain. It selects ARM64 or x86_64 from the release manifest,
46
+ verifies the SHA-256 digest and exact version before replacing
47
+ `~/.local/bin/borg`, and then runs step 2 for you:
48
+
49
+ ```bash
50
+ curl --proto '=https' --tlsv1.2 -fsSL https://install.betterborg.ai | sh
51
+ ```
52
+
53
+ 2. Activate the agent-host integrations:
54
+
55
+ ```bash
56
+ borg plugins install --all
57
+ ```
58
+
59
+ Then run `/reload-plugins` in any open Claude Code session, and start a new Codex session when prompted.
60
+
61
+ 3. From inside a Git repository, run the loop:
62
+
63
+ ```bash
64
+ borg trust # trust this worktree (machine-local)
65
+ borg init # register and analyze the repository
66
+ borg create my-feature # or: borg create my-feature --prd spec.md
67
+ borg plan start my-feature # agents plan, review, and iterate
68
+ borg plan approve my-feature # your gate — nothing is decomposed before this
69
+ borg task estimate my-feature # P50/P80 work and cost
70
+ borg execute my-feature # approve the estimate, then run
71
+ ```
72
+
73
+ `borg execute` hands off reviewed local branches. Add `--push` or `--pr` to publish them. `borg --help` is the full command index.
74
+
75
+ To try it without installing:
76
+
77
+ ```bash
78
+ npx --yes @betterborg/cli version
79
+ ```
80
+
81
+ Plugin activation needs a persistent install, so it is skipped under `npx`.
82
+
83
+ ## Requirements
84
+
85
+ - Python 3.11+, on macOS or Linux. On Windows, use a WSL2 shell.
86
+ - One agent transport: a `claude` or `codex` CLI on `PATH` and **already logged in**, or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` exported in your shell.
87
+
88
+ Keep provider keys in your shell or a secret manager, never in `.borg/config.toml` or any tracked file.
89
+
90
+ ## Documentation
91
+
92
+ - [Installation guide](docs/installation.md) — version pinning, WSL2, providers, recovery
93
+ - [Command guide](docs/commands.md) — bootstrap and initialization
94
+ - [Release runbook](docs/releasing.md) — for maintainers
95
+
96
+ ## Reporting bugs
97
+
98
+ File a [GitHub issue](https://github.com/betterborg/betterborg-cli/issues).
99
+
100
+ ## Contributing
101
+
102
+ See [AGENTS.md](AGENTS.md) for repository rules and the standard `make` targets.
103
+
104
+ ## License
105
+
106
+ Copyright 2026 BetterBorg. Licensed under the [MIT License](LICENSE). See [NOTICE](NOTICE) for attribution.
@@ -0,0 +1,83 @@
1
+ # BetterBorg CLI
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/betterborg.svg?style=flat-square)](https://pypi.org/project/betterborg/)
4
+ [![npm](https://img.shields.io/npm/v/@betterborg/cli.svg?style=flat-square)](https://www.npmjs.com/package/@betterborg/cli)
5
+ ![Python](https://img.shields.io/badge/Python-3.11%2B-brightgreen?style=flat-square)
6
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
7
+
8
+ BetterBorg is an AI engineering team for substantial software projects, not a chat window that makes an isolated edit. You give it a task or a PRD; agents investigate your real code, write a reviewed technical plan, decompose it into a dependency graph of tasks, and implement them — each in its own isolated Git worktree. You approve the plan before anything is decomposed, and the estimate before anything runs. It works locally, on your own Claude Code or Codex subscription.
9
+
10
+ > [!NOTE]
11
+ > Pre-alpha. Interfaces may change between releases.
12
+
13
+ ## Get started
14
+
15
+ 1. Install the CLI:
16
+
17
+ ```bash
18
+ pip install betterborg
19
+ ```
20
+
21
+ Or install the standalone release binary for Darwin or Linux, which needs
22
+ no Python toolchain. It selects ARM64 or x86_64 from the release manifest,
23
+ verifies the SHA-256 digest and exact version before replacing
24
+ `~/.local/bin/borg`, and then runs step 2 for you:
25
+
26
+ ```bash
27
+ curl --proto '=https' --tlsv1.2 -fsSL https://install.betterborg.ai | sh
28
+ ```
29
+
30
+ 2. Activate the agent-host integrations:
31
+
32
+ ```bash
33
+ borg plugins install --all
34
+ ```
35
+
36
+ Then run `/reload-plugins` in any open Claude Code session, and start a new Codex session when prompted.
37
+
38
+ 3. From inside a Git repository, run the loop:
39
+
40
+ ```bash
41
+ borg trust # trust this worktree (machine-local)
42
+ borg init # register and analyze the repository
43
+ borg create my-feature # or: borg create my-feature --prd spec.md
44
+ borg plan start my-feature # agents plan, review, and iterate
45
+ borg plan approve my-feature # your gate — nothing is decomposed before this
46
+ borg task estimate my-feature # P50/P80 work and cost
47
+ borg execute my-feature # approve the estimate, then run
48
+ ```
49
+
50
+ `borg execute` hands off reviewed local branches. Add `--push` or `--pr` to publish them. `borg --help` is the full command index.
51
+
52
+ To try it without installing:
53
+
54
+ ```bash
55
+ npx --yes @betterborg/cli version
56
+ ```
57
+
58
+ Plugin activation needs a persistent install, so it is skipped under `npx`.
59
+
60
+ ## Requirements
61
+
62
+ - Python 3.11+, on macOS or Linux. On Windows, use a WSL2 shell.
63
+ - One agent transport: a `claude` or `codex` CLI on `PATH` and **already logged in**, or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` exported in your shell.
64
+
65
+ Keep provider keys in your shell or a secret manager, never in `.borg/config.toml` or any tracked file.
66
+
67
+ ## Documentation
68
+
69
+ - [Installation guide](docs/installation.md) — version pinning, WSL2, providers, recovery
70
+ - [Command guide](docs/commands.md) — bootstrap and initialization
71
+ - [Release runbook](docs/releasing.md) — for maintainers
72
+
73
+ ## Reporting bugs
74
+
75
+ File a [GitHub issue](https://github.com/betterborg/betterborg-cli/issues).
76
+
77
+ ## Contributing
78
+
79
+ See [AGENTS.md](AGENTS.md) for repository rules and the standard `make` targets.
80
+
81
+ ## License
82
+
83
+ Copyright 2026 BetterBorg. Licensed under the [MIT License](LICENSE). See [NOTICE](NOTICE) for attribution.
@@ -0,0 +1,87 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "betterborg"
7
+ dynamic = ["version"]
8
+ description = "The open source BetterBorg command-line interface"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ license-files = ["LICENSE", "NOTICE"]
13
+ authors = [{ name = "BetterBorg" }]
14
+ classifiers = [
15
+ "Development Status :: 2 - Pre-Alpha",
16
+ "Environment :: Console",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.11",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Programming Language :: Python :: 3.13",
21
+ ]
22
+ dependencies = [
23
+ "click>=8.1,<9",
24
+ "mcp>=1.12,<2",
25
+ ]
26
+
27
+ [project.urls]
28
+ Homepage = "https://github.com/betterborg/betterborg-cli"
29
+ Repository = "https://github.com/betterborg/betterborg-cli"
30
+ Issues = "https://github.com/betterborg/betterborg-cli/issues"
31
+
32
+ [project.scripts]
33
+ borg = "betterborg_cli.cli:cli"
34
+
35
+ [dependency-groups]
36
+ binary = [
37
+ # 50.0.1 omitted glibc 2.17 wheels; keep release builds wheel-only.
38
+ "cryptography==50.0.0",
39
+ "pyinstaller>=6.16,<7",
40
+ "setuptools>=77",
41
+ "wheel",
42
+ ]
43
+ dev = [
44
+ "build>=1.2,<2",
45
+ "pyinstaller>=6.16,<7",
46
+ "pytest>=8,<9",
47
+ "ruff>=0.12.7,<1",
48
+ "setuptools>=77",
49
+ "wheel",
50
+ ]
51
+
52
+ [tool.setuptools.dynamic]
53
+ version = { attr = "betterborg_cli.__version__" }
54
+
55
+ [tool.setuptools.packages.find]
56
+ where = ["src"]
57
+
58
+ [tool.setuptools.package-data]
59
+ betterborg_cli = [
60
+ "planning/prompts/*.md",
61
+ "planning/schemas/*.json",
62
+ "repo_analysis/prompts/*.md",
63
+ "repo_analysis/schemas/*.json",
64
+ "store/migrations/*.sql",
65
+ "claude_plugin_bundle/marketplace/.claude-plugin/*.json",
66
+ "claude_plugin_bundle/marketplace/plugins/borg/.claude-plugin/*.json",
67
+ "claude_plugin_bundle/marketplace/plugins/borg/.mcp.json",
68
+ "claude_plugin_bundle/marketplace/plugins/borg/commands/*.md",
69
+ "claude_plugin_bundle/marketplace/plugins/borg/skills/*/*.md",
70
+ "codex_plugin_bundle/marketplace/.agents/plugins/*.json",
71
+ "codex_plugin_bundle/marketplace/plugins/borg/.codex-plugin/*.json",
72
+ "codex_plugin_bundle/marketplace/plugins/borg/.mcp.json",
73
+ "codex_plugin_bundle/marketplace/plugins/borg/skills/*/*.md",
74
+ ]
75
+
76
+ [tool.pytest.ini_options]
77
+ addopts = "-ra"
78
+ testpaths = ["tests"]
79
+ pythonpath = ["."]
80
+
81
+ [tool.ruff]
82
+ target-version = "py311"
83
+ line-length = 88
84
+ extend-exclude = [".betterborg-analysis", ".betterborg-task", ".orchestry"]
85
+
86
+ [tool.ruff.lint]
87
+ select = ["E", "F", "I", "UP", "B"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,106 @@
1
+ Metadata-Version: 2.4
2
+ Name: betterborg
3
+ Version: 0.1.0
4
+ Summary: The open source BetterBorg command-line interface
5
+ Author: BetterBorg
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/betterborg/betterborg-cli
8
+ Project-URL: Repository, https://github.com/betterborg/betterborg-cli
9
+ Project-URL: Issues, https://github.com/betterborg/betterborg-cli/issues
10
+ Classifier: Development Status :: 2 - Pre-Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Requires-Python: >=3.11
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ License-File: NOTICE
20
+ Requires-Dist: click<9,>=8.1
21
+ Requires-Dist: mcp<2,>=1.12
22
+ Dynamic: license-file
23
+
24
+ # BetterBorg CLI
25
+
26
+ [![PyPI](https://img.shields.io/pypi/v/betterborg.svg?style=flat-square)](https://pypi.org/project/betterborg/)
27
+ [![npm](https://img.shields.io/npm/v/@betterborg/cli.svg?style=flat-square)](https://www.npmjs.com/package/@betterborg/cli)
28
+ ![Python](https://img.shields.io/badge/Python-3.11%2B-brightgreen?style=flat-square)
29
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
30
+
31
+ BetterBorg is an AI engineering team for substantial software projects, not a chat window that makes an isolated edit. You give it a task or a PRD; agents investigate your real code, write a reviewed technical plan, decompose it into a dependency graph of tasks, and implement them — each in its own isolated Git worktree. You approve the plan before anything is decomposed, and the estimate before anything runs. It works locally, on your own Claude Code or Codex subscription.
32
+
33
+ > [!NOTE]
34
+ > Pre-alpha. Interfaces may change between releases.
35
+
36
+ ## Get started
37
+
38
+ 1. Install the CLI:
39
+
40
+ ```bash
41
+ pip install betterborg
42
+ ```
43
+
44
+ Or install the standalone release binary for Darwin or Linux, which needs
45
+ no Python toolchain. It selects ARM64 or x86_64 from the release manifest,
46
+ verifies the SHA-256 digest and exact version before replacing
47
+ `~/.local/bin/borg`, and then runs step 2 for you:
48
+
49
+ ```bash
50
+ curl --proto '=https' --tlsv1.2 -fsSL https://install.betterborg.ai | sh
51
+ ```
52
+
53
+ 2. Activate the agent-host integrations:
54
+
55
+ ```bash
56
+ borg plugins install --all
57
+ ```
58
+
59
+ Then run `/reload-plugins` in any open Claude Code session, and start a new Codex session when prompted.
60
+
61
+ 3. From inside a Git repository, run the loop:
62
+
63
+ ```bash
64
+ borg trust # trust this worktree (machine-local)
65
+ borg init # register and analyze the repository
66
+ borg create my-feature # or: borg create my-feature --prd spec.md
67
+ borg plan start my-feature # agents plan, review, and iterate
68
+ borg plan approve my-feature # your gate — nothing is decomposed before this
69
+ borg task estimate my-feature # P50/P80 work and cost
70
+ borg execute my-feature # approve the estimate, then run
71
+ ```
72
+
73
+ `borg execute` hands off reviewed local branches. Add `--push` or `--pr` to publish them. `borg --help` is the full command index.
74
+
75
+ To try it without installing:
76
+
77
+ ```bash
78
+ npx --yes @betterborg/cli version
79
+ ```
80
+
81
+ Plugin activation needs a persistent install, so it is skipped under `npx`.
82
+
83
+ ## Requirements
84
+
85
+ - Python 3.11+, on macOS or Linux. On Windows, use a WSL2 shell.
86
+ - One agent transport: a `claude` or `codex` CLI on `PATH` and **already logged in**, or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` exported in your shell.
87
+
88
+ Keep provider keys in your shell or a secret manager, never in `.borg/config.toml` or any tracked file.
89
+
90
+ ## Documentation
91
+
92
+ - [Installation guide](docs/installation.md) — version pinning, WSL2, providers, recovery
93
+ - [Command guide](docs/commands.md) — bootstrap and initialization
94
+ - [Release runbook](docs/releasing.md) — for maintainers
95
+
96
+ ## Reporting bugs
97
+
98
+ File a [GitHub issue](https://github.com/betterborg/betterborg-cli/issues).
99
+
100
+ ## Contributing
101
+
102
+ See [AGENTS.md](AGENTS.md) for repository rules and the standard `make` targets.
103
+
104
+ ## License
105
+
106
+ Copyright 2026 BetterBorg. Licensed under the [MIT License](LICENSE). See [NOTICE](NOTICE) for attribution.
@@ -0,0 +1,166 @@
1
+ LICENSE
2
+ NOTICE
3
+ README.md
4
+ pyproject.toml
5
+ src/betterborg.egg-info/PKG-INFO
6
+ src/betterborg.egg-info/SOURCES.txt
7
+ src/betterborg.egg-info/dependency_links.txt
8
+ src/betterborg.egg-info/entry_points.txt
9
+ src/betterborg.egg-info/requires.txt
10
+ src/betterborg.egg-info/top_level.txt
11
+ src/betterborg_cli/__init__.py
12
+ src/betterborg_cli/__main__.py
13
+ src/betterborg_cli/claude_plugin.py
14
+ src/betterborg_cli/cli.py
15
+ src/betterborg_cli/codex_plugin.py
16
+ src/betterborg_cli/execution_estimate.py
17
+ src/betterborg_cli/mcp_server.py
18
+ src/betterborg_cli/onboarding.py
19
+ src/betterborg_cli/plugin_activation.py
20
+ src/betterborg_cli/plugin_installation.py
21
+ src/betterborg_cli/plugins.py
22
+ src/betterborg_cli/prd_session.py
23
+ src/betterborg_cli/repo_paths.py
24
+ src/betterborg_cli/repository_config.py
25
+ src/betterborg_cli/repository_files.py
26
+ src/betterborg_cli/repository_service.py
27
+ src/betterborg_cli/workflow_service.py
28
+ src/betterborg_cli/workspace_trust.py
29
+ src/betterborg_cli/agent_runtime/__init__.py
30
+ src/betterborg_cli/agent_runtime/anthropic.py
31
+ src/betterborg_cli/agent_runtime/api_adapter.py
32
+ src/betterborg_cli/agent_runtime/api_tools.py
33
+ src/betterborg_cli/agent_runtime/base.py
34
+ src/betterborg_cli/agent_runtime/claude.py
35
+ src/betterborg_cli/agent_runtime/codex.py
36
+ src/betterborg_cli/agent_runtime/mock.py
37
+ src/betterborg_cli/agent_runtime/native_cli.py
38
+ src/betterborg_cli/agent_runtime/openai.py
39
+ src/betterborg_cli/agent_runtime/pricing.py
40
+ src/betterborg_cli/agent_runtime/process.py
41
+ src/betterborg_cli/agent_runtime/retry.py
42
+ src/betterborg_cli/agent_runtime/selection.py
43
+ src/betterborg_cli/agent_runtime/structured.py
44
+ src/betterborg_cli/claude_plugin_bundle/__init__.py
45
+ src/betterborg_cli/claude_plugin_bundle/marketplace/.claude-plugin/marketplace.json
46
+ src/betterborg_cli/claude_plugin_bundle/marketplace/plugins/borg/.mcp.json
47
+ src/betterborg_cli/claude_plugin_bundle/marketplace/plugins/borg/.claude-plugin/plugin.json
48
+ src/betterborg_cli/claude_plugin_bundle/marketplace/plugins/borg/commands/borg.md
49
+ src/betterborg_cli/claude_plugin_bundle/marketplace/plugins/borg/skills/orchestrate/SKILL.md
50
+ src/betterborg_cli/codex_plugin_bundle/__init__.py
51
+ src/betterborg_cli/codex_plugin_bundle/marketplace/.agents/plugins/marketplace.json
52
+ src/betterborg_cli/codex_plugin_bundle/marketplace/plugins/borg/.mcp.json
53
+ src/betterborg_cli/codex_plugin_bundle/marketplace/plugins/borg/.codex-plugin/plugin.json
54
+ src/betterborg_cli/codex_plugin_bundle/marketplace/plugins/borg/skills/orchestrate/SKILL.md
55
+ src/betterborg_cli/host_execution/__init__.py
56
+ src/betterborg_cli/host_execution/_agent_phase.py
57
+ src/betterborg_cli/host_execution/_locking.py
58
+ src/betterborg_cli/host_execution/coding.py
59
+ src/betterborg_cli/host_execution/compose.py
60
+ src/betterborg_cli/host_execution/environment.py
61
+ src/betterborg_cli/host_execution/git.py
62
+ src/betterborg_cli/host_execution/guard.py
63
+ src/betterborg_cli/host_execution/merge.py
64
+ src/betterborg_cli/host_execution/preflight.py
65
+ src/betterborg_cli/host_execution/review.py
66
+ src/betterborg_cli/host_execution/sanity.py
67
+ src/betterborg_cli/host_execution/scheduler.py
68
+ src/betterborg_cli/host_execution/service.py
69
+ src/betterborg_cli/host_execution/worktrees.py
70
+ src/betterborg_cli/planning/__init__.py
71
+ src/betterborg_cli/planning/architect.py
72
+ src/betterborg_cli/planning/plan_contracts.py
73
+ src/betterborg_cli/planning/pm.py
74
+ src/betterborg_cli/planning/supervisor.py
75
+ src/betterborg_cli/planning/task_publication.py
76
+ src/betterborg_cli/planning/task_render.py
77
+ src/betterborg_cli/planning/task_validation.py
78
+ src/betterborg_cli/planning/tech_lead.py
79
+ src/betterborg_cli/planning/turns.py
80
+ src/betterborg_cli/planning/worktree.py
81
+ src/betterborg_cli/repo_analysis/__init__.py
82
+ src/betterborg_cli/repo_analysis/analyzer.py
83
+ src/betterborg_cli/repo_analysis/discovery.py
84
+ src/betterborg_cli/repo_analysis/improvement_prds.py
85
+ src/betterborg_cli/repo_analysis/prompts_manager.py
86
+ src/betterborg_cli/repo_analysis/reporting.py
87
+ src/betterborg_cli/repo_analysis/scoring.py
88
+ src/betterborg_cli/repo_analysis/text_rendering.py
89
+ src/betterborg_cli/store/__init__.py
90
+ src/betterborg_cli/store/models.py
91
+ src/betterborg_cli/store/sqlite.py
92
+ src/betterborg_cli/store/migrations/001_initial.sql
93
+ src/betterborg_cli/store/migrations/002_analysis_history.sql
94
+ src/betterborg_cli/store/migrations/003_borg_prd_sessions.sql
95
+ src/betterborg_cli/store/migrations/004_planning_state.sql
96
+ src/betterborg_cli/store/migrations/005_task_generations.sql
97
+ src/betterborg_cli/store/migrations/006_execution_ownership.sql
98
+ src/betterborg_cli/store/migrations/007_open_execution_attempts.sql
99
+ src/betterborg_cli/store/migrations/008_execution_attempt_finalization.sql
100
+ src/betterborg_cli/store/migrations/009_execution_incarnations.sql
101
+ src/betterborg_cli/store/migrations/010_run_environment_attempts.sql
102
+ src/betterborg_cli/store/migrations/011_execution_decisions.sql
103
+ src/betterborg_cli/store/migrations/__init__.py
104
+ tests/test_adapter_harness.py
105
+ tests/test_agent_api_tools.py
106
+ tests/test_agent_process.py
107
+ tests/test_agent_runtime.py
108
+ tests/test_agent_selection.py
109
+ tests/test_anthropic_adapter.py
110
+ tests/test_api_adapter_contract.py
111
+ tests/test_binary_release.py
112
+ tests/test_claude_adapter.py
113
+ tests/test_claude_plugin.py
114
+ tests/test_cli.py
115
+ tests/test_cli_execute.py
116
+ tests/test_cli_plan_approval.py
117
+ tests/test_cli_planning.py
118
+ tests/test_cli_tasks.py
119
+ tests/test_codex_adapter.py
120
+ tests/test_codex_plugin.py
121
+ tests/test_distribution.py
122
+ tests/test_execution_estimate.py
123
+ tests/test_execution_preflight.py
124
+ tests/test_final_release.py
125
+ tests/test_foundation_fixtures.py
126
+ tests/test_github_release_verification.py
127
+ tests/test_host_coding.py
128
+ tests/test_host_execution_service.py
129
+ tests/test_host_merge.py
130
+ tests/test_host_preflight.py
131
+ tests/test_host_sanity.py
132
+ tests/test_host_scheduler.py
133
+ tests/test_host_worktrees.py
134
+ tests/test_install_script.py
135
+ tests/test_mcp_server.py
136
+ tests/test_npm_release.py
137
+ tests/test_onboarding.py
138
+ tests/test_openai_adapter.py
139
+ tests/test_planning_architect.py
140
+ tests/test_planning_plan_contracts.py
141
+ tests/test_planning_task_publication.py
142
+ tests/test_planning_task_validation.py
143
+ tests/test_planning_tech_lead.py
144
+ tests/test_planning_worktree.py
145
+ tests/test_plugin_activation.py
146
+ tests/test_plugins.py
147
+ tests/test_prd_session.py
148
+ tests/test_public_installations.py
149
+ tests/test_public_tree.py
150
+ tests/test_release_workflow.py
151
+ tests/test_repo_analysis_analyzer.py
152
+ tests/test_repo_analysis_discovery.py
153
+ tests/test_repo_analysis_improvement_prds.py
154
+ tests/test_repo_analysis_prompts_manager.py
155
+ tests/test_repo_analysis_reporting.py
156
+ tests/test_repo_analysis_scoring.py
157
+ tests/test_repo_paths.py
158
+ tests/test_repository_config.py
159
+ tests/test_repository_files.py
160
+ tests/test_repository_initialization.py
161
+ tests/test_store.py
162
+ tests/test_store_execution.py
163
+ tests/test_store_execution_decisions.py
164
+ tests/test_store_planning.py
165
+ tests/test_store_task_generations.py
166
+ tests/test_workspace_trust.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ borg = betterborg_cli.cli:cli
@@ -0,0 +1,2 @@
1
+ click<9,>=8.1
2
+ mcp<2,>=1.12
@@ -0,0 +1 @@
1
+ betterborg_cli
@@ -0,0 +1,3 @@
1
+ """BetterBorg CLI package."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,8 @@
1
+ """Executable module used by the standalone Borg binary."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from betterborg_cli.cli import cli
6
+
7
+ if __name__ == "__main__":
8
+ cli()