Writing a file in a way that it either fully succeeds or does not happen at all. The system writes to a temporary file first, then renames it to the target. If the process crashes mid-write, the original file is still intact. The word "atomic" comes from physics — something that cannot be split into smaller parts. An atomic write cannot be "half done."

A technique for preventing race conditions. Before modifying a task, you check that its version number matches what you expect. If someone else changed it in the meantime (bumping the version), your modification is rejected. You must re-read the latest version and try again. Used in databases, distributed systems, and CPU instructions worldwide.

A system that automatically runs checks (formatting, linting, tests) every time you push code to GitHub. If any check fails, the commit is marked with a red X. If all pass, green checkmark. The idea is to "continuously" verify that new code does not break existing code, rather than finding out days later.

A program you interact with by typing commands in a terminal, as opposed to clicking buttons in a graphical interface. The hq tool is a CLI — you type hq task list --team demo to interact with it.

Multiple things happening at the same time. In this project, multiple AI agents might try to claim the same task at the exact same instant. The system must handle this safely so that exactly one agent wins and the others get a clean error, not corrupted data.

A number that a program returns when it finishes. Zero means success, anything else means something went wrong. Different non-zero codes indicate different problems. You can check the exit code in bash with echo $? after running a command.

An operating system feature that lets one program "lock" a file so other programs have to wait before accessing it. Like a bathroom door lock — if someone is inside, you wait until they come out. Used to prevent two agents from modifying the same task file simultaneously.

A system call that forces the operating system to write data from its memory buffers to the physical disk. Without fsync, data might sit in memory for seconds or minutes before being written, and a power failure could lose it. In atomic writes, fsync ensures the temp file is fully on disk before the rename.

A programming language created by Google in 2009. Popular for command-line tools, web servers, and systems programming. Known for simplicity, fast compilation, excellent concurrency support (goroutines), and producing single-binary executables with no dependencies.

Go's lightweight version of a thread — a way to run code concurrently. You can have thousands of goroutines running at once with minimal memory overhead. In our tests, we launch 10 goroutines all racing to claim the same task to verify our concurrency safety mechanisms work.

A periodic "I'm still alive" signal. When an agent is working on a long task, it sends a heartbeat every 10 minutes to extend its lease. Without heartbeats, the system would think the agent crashed after 30 minutes and let another agent take over.

The property where doing something twice has the same effect as doing it once. If an agent sends "task complete" and then sends it again (maybe it crashed and retried), the second time is silently ignored. The idempotency key is a unique string that identifies each operation so the system can detect duplicates.

A text format for storing structured data. Looks like: {"name": "task1", "status": "pending"}. Despite the name, it is used in virtually every programming language, not just JavaScript. All task and inbox files in AI Agents HQ are JSON.

A time-limited reservation on a task. When an agent claims a task, it gets a lease that expires in 30 minutes (the TTL — Time To Live). If the agent finishes before the lease expires, great. If it crashes, the lease expires and another agent can take over. This prevents tasks from getting stuck forever.

A tool that analyzes your code without running it and flags potential problems — bugs, bad style, unused variables, unchecked errors. Think of it as a really thorough spell checker for code. Go's popular linter is golangci-lint, which runs dozens of different checks.

A protocol for giving AI models access to external tools and data sources. For example, an MCP server might provide file system access, database queries, or API calls. Tasks can specify which MCP servers they need via the required_mcps field.

Go's system for organizing and versioning code. The go.mod file declares the project's name (like github.com/gbas/ai-agents-hq) and any external dependencies. Similar to package.json in Node.js or requirements.txt in Python.

A number (currently 2) that agents include in every state-changing command. If the protocol changes in a future version, old agents are rejected with a clear error instead of silently corrupting data. This is a safety net for upgrades.

A bug that occurs when two things try to read and write the same data at the same time, and the result depends on which one happens to go first. Race conditions are notoriously hard to find because they may only occur under specific timing conditions. Go's race detector catches them automatically during testing.

A Go tool that instruments your code at compile time to detect data races. When two goroutines access the same memory without synchronization, it immediately reports the exact location. Always run tests with -race for concurrent code.

A separate program launched by another program. Our integration tests compile hq into a binary and then run it as a subprocess — exactly like you would type the command in a terminal. This tests the real behavior end-to-end.

A test that checks one small piece of code in isolation — a single function or a single behavior. Unit tests are fast (milliseconds), do not touch the file system or network, and catch regressions immediately.

A test that checks multiple pieces working together. Our integration tests run the full hq binary, create real files, and verify the complete workflow from command-line input to file output. Slower than unit tests but catches issues in the connections between components.

Go's built-in code formatter. It enforces one consistent style — everyone's Go code looks the same. There are no configuration options and no style debates. Just run gofmt -w . and commit the result.

A human-readable data format similar to JSON but with less punctuation. Uses indentation instead of braces. The docs.yaml configuration file for Phosphor is written in YAML. Looks like: title: "My Site" instead of {"title": "My Site"}.

Another configuration file format, used by Codex's .codex/config.toml. Similar to INI files with [sections] and key = "value" pairs. More structured than YAML, less verbose than JSON.