Skip to main content

Aider

Aider is a terminal-based pair programming tool that works with your local git repository. It frequently produces changelogs, design notes, implementation summaries, and code documentation as part of development sessions. OpenDocs gives those files a shareable URL without leaving the terminal.

Setup​

Install the CLI and authenticate:

npm install -g @opendocs.cc/cli
opendocs login

Aider supports conventions files and in-chat commands. You can reference the OpenDocs SKILL.md at the start of a session or add it to your Aider configuration so the publishing workflow is always available.

To load the skill in a session:

/read SKILL.md

Example prompts​

Publish a new doc:

Generate a changelog for the recent commits as Markdown, publish
it with OpenDocs, and print the final URL.

Document a refactor:

We just refactored the user service. Write a Markdown summary of
what changed, why, and any migration steps. Publish it to OpenDocs
with the tag "refactor" and return the link.

Update an existing doc:

Pull post abc123 from OpenDocs, add the new caching strategy
section, and publish the update.

Publish with a specific slug:

Write an API migration guide from v1 to v2 as Markdown. Publish
it to OpenDocs with slug "api-v1-to-v2" and tags "migration, api".
Return the URL.

Common workflows​

Changelog generation​

Aider has access to your git history, which makes it effective at generating changelogs:

Look at the commits since the v2.3.0 tag and generate a
user-facing changelog as Markdown. Group changes by category
(features, fixes, breaking changes). Publish it to OpenDocs.
opendocs publish changelog-v2.4.md --slug changelog-v2.4 --tags "changelog,release" --json

Post-session documentation​

At the end of a pairing session, ask Aider to document what was accomplished:

Summarize everything we changed in this session as a Markdown
doc. Include the files modified, the reasoning behind key
decisions, and any follow-up items. Publish it to OpenDocs.

Design notes during development​

When making architectural decisions, capture them as docs in real time:

We decided to use Redis for session storage instead of PostgreSQL.
Write an ADR as Markdown covering the context, alternatives we
considered, and the decision. Publish it to OpenDocs with tags
"adr, architecture".

Iterative documentation​

For docs that grow over a project, use update to revise the same URL:

# First publish
opendocs publish design-notes.md --json
# Returns: { "postId": "abc123", "url": "..." }

# After more work
opendocs update abc123 design-notes.md --json

Using SKILL.md with Aider​

The most reliable way to teach Aider the OpenDocs workflow:

  1. Add SKILL.md to your project root (or download it from the GitHub repo)
  2. At the start of an Aider session, run /read SKILL.md
  3. Aider now knows all the CLI commands and will use them correctly

Alternatively, if you always want OpenDocs available, add the SKILL.md reference to your Aider configuration file.

Tips​

  • Load SKILL.md with /read — Aider's /read command is the quickest way to teach it the workflow in any session
  • Use --json — Aider works in the terminal where JSON output is easy to parse and reference
  • Leverage git context — Aider can read your commit history, diffs, and branch info to generate accurate changelogs and summaries
  • Capture decisions early — publishing an ADR during the session is faster than writing it up after the fact