Skip to content

dtgbao/swe-wiki

v0.2.1

Domain-first, Git-synced software engineering knowledge base for Codex.

GitHub

SWE Wiki Plugin

Maintain a persistent, domain-first Markdown knowledge base for software engineering decisions, blueprints, practices, conventions, systems, and reusable answers. The wiki lives in a dedicated Git repository so it can be synchronized safely across computers.

Install

Add this repository as a Codex marketplace, then install the bundled plugin:

codex plugin marketplace add dtgbao/agent-skills
codex plugin add swe-wiki@bao-plugins

Start a new Codex task after installation so the bundled skill is available.

First Use

Ask Codex to set up the SWE wiki. It will ask for:

  1. A local wiki directory, defaulting to ~/.swe-wiki.
  2. An existing Git repository used for synchronization.

Use a private repository when the wiki may contain proprietary information. Authentication remains managed by Git or SSH; do not put credentials in the repository URL.

Setup clones an existing repository or initializes an empty one, creates the wiki structure, saves the local root in ~/.config/swe-wiki/config.json, and performs the initial push.

Workflows

  • init: Create or repair a local wiki without invoking Git.
  • ingest: Classify a source into an approved primary domain, preserve local inputs under raw/<domain>/, and synthesize reusable engineering knowledge.
  • migrate: Preview and explicitly apply a legacy kind-first to domain-first migration.
  • query: Search the wiki and answer with page citations.
  • lint: Check mechanical structure and semantic health.
  • sync: Explicitly commit, rebase, and push without force.

Synchronization is never automatic. If a rebase conflicts, the script aborts it, preserves the local commit, and reports the files requiring user-guided resolution.

Domain Layout

Knowledge is organized by the technical domain that owns it, not by page kind or source course structure:

wiki/
├── index.md
└── aws/
    ├── index.md
    └── iam/
        ├── index.md
        ├── durable-page.md
        └── sources/
            ├── index.md
            └── source-page.md
raw/
└── aws/
    └── iam/
        └── source-files

The root index links top-level domains; every nested wiki directory has its own local index. Page kind remains frontmatter metadata. Before ingestion, Codex reads the source, recommends a primary domain and alternatives, and waits for approval.

The CLI requires that approved domain explicitly:

python3 skills/swe-wiki/scripts/swe_wiki.py ingest ./lesson.txt \
  --asset ./slide.png \
  --domain aws/iam \
  --title "IAM lesson"

Legacy migrations use a JSON assignment manifest and preview by default. Apply only after reviewing the exact moves:

python3 skills/swe-wiki/scripts/swe_wiki.py migrate ./migration.json
python3 skills/swe-wiki/scripts/swe_wiki.py migrate ./migration.json --apply

Requirements

  • macOS or Linux
  • Python 3
  • Git with user-managed authentication and commit identity

The implementation uses only the Python standard library and the git executable.

Development

Run the isolated test suite:

python3 -m unittest discover -s plugins/swe-wiki/tests -v