Skip to content

Commit d823dc3

Browse files
cartermccanncartermccann
committed
Prepare repository for public release
1 parent 68cc33a commit d823dc3

18 files changed

Lines changed: 667 additions & 139 deletions

‎.editorconfig‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
trim_trailing_whitespace = true
8+
9+
[*.py]
10+
indent_size = 4
11+
indent_style = space
12+
13+
[*.{md,yml,yaml}]
14+
indent_size = 2
15+
indent_style = space

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
name: Bug report
2+
description: Report a reproducible patch, loading, discovery, or dictation failure
3+
title: "[bug] "
4+
labels:
5+
- bug
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
Do not upload app bundles, proprietary Work Louder packages, secrets,
11+
account data, or unreviewed full logs.
12+
- type: input
13+
id: codex-version
14+
attributes:
15+
label: Codex desktop version
16+
placeholder: 26.715.72359
17+
validations:
18+
required: true
19+
- type: input
20+
id: overlay-version
21+
attributes:
22+
label: codex-desktop-linux version or commit
23+
placeholder: 0.10.2 / efcf40b5ab41
24+
validations:
25+
required: true
26+
- type: input
27+
id: system
28+
attributes:
29+
label: System
30+
placeholder: NixOS unstable, x86_64-linux, Electron 42.3.0
31+
validations:
32+
required: true
33+
- type: textarea
34+
id: status
35+
attributes:
36+
label: Status output
37+
description: Paste all three script status outputs.
38+
render: text
39+
validations:
40+
required: true
41+
- type: dropdown
42+
id: layer
43+
attributes:
44+
label: Failing layer
45+
options:
46+
- Feature activation
47+
- ASAR/native packaging
48+
- Dynamic linkage
49+
- Device discovery
50+
- Key or RGB events
51+
- Microphone capture
52+
- Transcription/insertion
53+
- Rollback
54+
validations:
55+
required: true
56+
- type: textarea
57+
id: reproduction
58+
attributes:
59+
label: Reproduction steps
60+
validations:
61+
required: true
62+
- type: textarea
63+
id: logs
64+
attributes:
65+
label: Sanitized relevant log lines
66+
description: Remove account data, tokens, personal paths, and unrelated content.
67+
render: text
68+
- type: checkboxes
69+
id: checks
70+
attributes:
71+
label: Safety checks
72+
options:
73+
- label: I used a fresh Electron main process after applying the patches.
74+
required: true
75+
- label: I removed secrets, account data, and proprietary files.
76+
required: true

‎.github/pull_request_template.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## Summary
2+
3+
<!-- What changed and why? -->
4+
5+
## Compatibility
6+
7+
- Codex desktop:
8+
- Electron:
9+
- codex-desktop-linux:
10+
- Architecture/distribution:
11+
12+
## Verification
13+
14+
- [ ] `make check`
15+
- [ ] Applied against a disposable overlay copy
16+
- [ ] Re-applying is idempotent
17+
- [ ] Restore recovers the original state
18+
- [ ] Tested with a fresh Electron main process
19+
20+
## Safety
21+
22+
- [ ] No proprietary app/device-kit files are included
23+
- [ ] No secrets, account data, or personal filesystem paths are included
24+
- [ ] Unknown bundle states fail closed

‎.github/workflows/ci.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
test:
12+
runs-on: ubuntu-latest
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
python-version:
17+
- "3.10"
18+
- "3.11"
19+
- "3.12"
20+
- "3.13"
21+
22+
steps:
23+
- uses: actions/checkout@v4
24+
- uses: actions/setup-python@v5
25+
with:
26+
python-version: ${{ matrix.python-version }}
27+
- name: Compile
28+
run: python -m py_compile scripts/*.py tests/*.py
29+
- name: Test
30+
run: python -m unittest discover -s tests -v

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,12 @@ __pycache__/
22
*.py[cod]
33
*.tmp
44
.DS_Store
5+
.env
6+
.env.*
7+
node_modules/
8+
vendor/
9+
codex-desktop-overlay/
10+
*.asar
11+
*.asar.unpacked/
12+
*.node
13+
*.before-codex-micro-*

‎CHANGELOG.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented here.
4+
5+
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6+
7+
## Unreleased
8+
9+
## 0.1.0 - 2026-07-23
10+
11+
### Added
12+
13+
- Exact feature-gate patch for Codex Micro and in-composer dictation.
14+
- Reversible ASAR native-module indexing repair.
15+
- Reversible NixOS `libusb` launcher-path patch.
16+
- Unit tests for gate, launcher, and native-module inspection logic.
17+
- Architecture, troubleshooting, and investigation documentation.
18+
- Explicit separation from the standalone `micro-herdr` bridge.

‎CONTRIBUTING.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Contributing
2+
3+
Thanks for helping make Codex Micro support on Linux less adventurous.
4+
5+
## Scope
6+
7+
Good contributions include:
8+
9+
- compatibility updates for new Codex desktop Linux overlay builds;
10+
- safer detection, backup, verification, and rollback logic;
11+
- additional NixOS architectures or reproducible runtime configurations;
12+
- sanitized diagnostics and confirmed compatibility reports;
13+
- documentation corrections.
14+
15+
Please keep standalone agent/shell bindings in
16+
[`micro-herdr`](https://github.com/cartermccann/micro-herdr). This repository
17+
is specifically for native Codex desktop integration.
18+
19+
## Ground rules
20+
21+
- Do not commit Codex app bundles, ASAR files, Work Louder packages, firmware,
22+
device-kit code, or other proprietary artifacts.
23+
- Do not upload secrets, account data, full application logs, or personally
24+
identifying filesystem paths.
25+
- Preserve reversible behavior. A patch must have `status`, apply, verification,
26+
and restore paths.
27+
- Refuse unknown bundle states instead of broadening a regular expression until
28+
it happens to match.
29+
- Document the exact app, overlay, Electron, architecture, and dependency
30+
versions used for a compatibility claim.
31+
32+
## Development setup
33+
34+
Python `3.10+` is sufficient; the tools use only the standard library.
35+
36+
```bash
37+
git clone https://github.com/cartermccann/codex-micro-linux.git
38+
cd codex-micro-linux
39+
make check
40+
```
41+
42+
## Updating for a new app build
43+
44+
1. Start from an unmodified overlay.
45+
2. Record the Codex app, Electron, and overlay versions.
46+
3. Run every tool’s `status` action.
47+
4. Inspect changed feature-gate call sites and native-module paths.
48+
5. Update exact match counts and tests.
49+
6. Apply against a disposable overlay copy.
50+
7. Test idempotence and full restore.
51+
8. Test on a fresh Electron main process.
52+
9. Report each verification layer separately; do not infer dictation success
53+
from native-module loading.
54+
55+
## Pull requests
56+
57+
Include:
58+
59+
- the problem and observed error;
60+
- affected versions and architecture;
61+
- why the change is narrowly scoped;
62+
- test output;
63+
- apply/restore evidence;
64+
- sanitized log excerpts where useful.
65+
66+
Run before opening a PR:
67+
68+
```bash
69+
make check
70+
git diff --check
71+
```

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Carter McCann
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.

‎Makefile‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.PHONY: check compile test
2+
3+
check: compile test
4+
5+
compile:
6+
python3 -m py_compile scripts/*.py tests/*.py
7+
8+
test:
9+
python3 -m unittest discover -s tests -v

0 commit comments

Comments
 (0)