Get the most out of your CrocoNile tools.

1Overview

CrocoNile Software builds AI tools that live in GitHub and work on your pull requests, repositories and issues. You install them like any GitHub App, choose the repositories they may use, and they respond right where your team already works.

What you need

• A GitHub account, or a GitHub organization where you are an owner or administrator.
• At least one repository you want the apps to work on.
• That's all. There is nothing to download, host or configure.

2Quick start

From zero to your first result in about five minutes.

1. Install an appOpen the app's GitHub page, click Install, choose your account or organization, and select the repositories it may use. See Installing an app.
2. Your free trial starts automaticallyThere is no sign-up form. Installing creates your CrocoNile account with a 14-day free trial and a starting token allowance.
3. Use it where you already work
   • ArchBot: open a (non-draft) pull request.
   • ArchMapApp: push a commit, or comment @archmap and a question on an issue.
   • ArchSpec: add the archspec label to an issue.
4. Check your balance any timeSign in at your CrocoNile account page with GitHub to see tokens, usage and billing. See Your account & tokens.

3Installing an app

1. Open the app's GitHub page and click InstallIf you belong to several accounts, GitHub asks where to install it. Choose a personal account or an organization.
2. Choose repositoriesPick Only select repositories and tick the ones you want, or All repositories. You can change this later.
3. Review the access and confirmGitHub lists exactly what the app can do (see the table below). Click Install.

What each app can access

Changing or removing access

You stay in control. On GitHub open Settings → Applications → Installed GitHub Apps (for an organization: Organization settings → Installed GitHub Apps), click Configure next to the app, then add or remove repositories, or Uninstall. Uninstalling stops the app immediately.

4Your account & tokens

One account covers every CrocoNile app you install — one trial, one subscription, one balance.

How to sign in

1. Open your account pageGo to the CrocoNile account page (the link in any app comment that says Manage your account goes to the same place).
2. Click “Sign in with GitHub”Approve the request. We only read your GitHub username and the organizations you administer, so we can show you the right account.
3. Pick an account if you have severalYou can open your personal account and any organization you administer.

What you will see

Tokens, in plain words

AI tools “read” and “write” in small units called tokens. Each time an app does work for you — reviewing a pull request, updating your architecture map, answering a question, writing a plan — the AI model uses some tokens, and exactly that amount is taken from your balance. Bigger changes and longer answers use more. Work that fails isn't deducted from your balance.

Free trial, subscription and top-ups

When apps pause

An app pauses — without using any tokens — when your trial has ended with no subscription, a payment has failed, you cancelled, or your balance has reached zero.

• ArchBot and ArchSpec post a short “subscription required” note on the pull request or issue, with a link to your account page.
• ArchMapApp posts the same note when you ask it a question. A paused push simply doesn't update ARCHITECTURE.md.

Subscribe or buy a pack and the apps resume on the next pull request, push or request. Nothing is lost; the paused work just isn't done retroactively.

5ArchBot

Your architecture rules, enforced on every pull request — before a human reviewer has to say it.

What it does

When a pull request is opened or updated, ArchBot reads the changes, compares them with the rules in your repository, and leaves an inline comment on each line that breaks a rule. If nothing breaks, it says so. It comments only; by default it never blocks a merge.

How it works, step by step

• Runs on: a pull request being opened, and every new push to it.
• Skips: draft pull requests. Mark the PR Ready for review and push a commit (or reopen it) to get a review.
• Rules come from the file .architecture-rules.md in the root of the branch the PR targets. If there isn't one, ArchBot falls back to a sensible default rule set.
• Very large changes: the first part of an extremely large diff is reviewed; the rest is skipped.

What you will see

An inline comment, shown on the line that breaks the rule.

When everything is fine. During the trial, a footer shows your days left.

Writing your rules

Create a file named .architecture-rules.md in the root of your repository (the dot at the start is part of the name). Write your rules in plain English, one per item. ArchBot treats the file as the standard to hold the code to.

Copy# Architecture rules

1. **Database access lives in the repository layer.** Route handlers must not
   run queries directly; they call a function in `app/repositories/`.
2. **Every database call is wrapped in try/except** and handles the failure
   explicitly (log it and return a controlled error).
3. **No raw SQL built with string concatenation or f-strings.** Use
   parameterized queries.
4. **No secrets in source code.** Read them from environment variables.
5. **Public functions and classes have docstrings.**
6. **Use the logging module, not print().**

Your rules take effect for pull requests that target a branch containing the file. Commit and merge it first.

Questions

6ArchMapApp

A map of your codebase that updates itself, and a teammate that can answer questions about it.

What it does

• Keeps ARCHITECTURE.md up to date. After you push, ArchMapApp reads your source files, works out how the pieces depend on each other, and writes a document with a C4-style diagram and a plain-English summary of the system.
• Answers questions. Mention @archmap in an issue or pull request comment and ask anything about the codebase.

Languages understood: Python, JavaScript / JSX, TypeScript / TSX, Go, Rust, Java, C#, C++ and C. Folders such as node_modules, vendor, dist and build are ignored.

The architecture document

1. Push to your repositoryAny push triggers an update.
2. ArchMapApp commits ARCHITECTURE.mdIt is saved to your default branch with a commit message ending in [ArchMap AI]. That commit does not trigger another update, so there is no loop.
3. Open the file on GitHubGitHub draws the diagram right in the page. It contains the detected tech stack, the architecture diagram and a three-paragraph summary.

Asking questions

Write a comment on any issue (or pull request conversation) that includes @archmap followed by your question:

@archmap where is user authentication handled, and which modules depend on it?

Questions

7ArchSpec

From “we should build this” to a concrete plan, written right on the issue.

What it does

ArchSpec reads an issue together with your repository — the file list, your ARCHITECTURE.md and your .architecture-rules.md — and posts one comment with an implementation plan the developer can start from.

How to ask for a plan

/archspec focus on backwards compatibility and keep the change behind a feature flag

To regenerate a plan after the issue changes, comment /archspec again. A plan usually appears within seconds.

What the plan contains

8Using them together

Each app is useful alone. Together they cover the loop from idea to merged code.

One shared token balance powers all of it, so the Usage-by-app chart on your account page shows where your tokens go.

A good first week

1. Install ArchMapApp first and let it write your first ARCHITECTURE.md.
2. Write 5–10 rules in .architecture-rules.md, merge them, then install ArchBot.
3. Install ArchSpec and try it on the next issue that needs a design.
4. Check your account page after a few days to see what each app uses.

9Troubleshooting

10Data & access

• You choose what an app can see. It only works on the repositories you select, and you can change that or uninstall at any time from GitHub.
• Your code is used to produce your result. To review a change, map a repository or write a plan, the relevant code and text are sent to an AI model provider for processing.
• Billing is handled by Stripe. We never see or store your card number.
• Signing in uses GitHub. We read only your username and the organizations you administer.
• Secrets. Don't commit secrets to your repositories — the apps read code, and ArchBot is happy to remind you of that rule.

For questions about data handling or for a data-processing agreement, contact hello@croconilesoftware.com.

11Glossary

12Support

We're happy to help with installation, billing and anything that doesn't behave as described here.

To help us answer quickly, include your GitHub username or organization, the app involved, and a link to the pull request or issue where you saw the problem.