Before planning code changes or reviewing code, read
Agent Rules. Follow the Task Index to the
owning module and read pages whose Read when trigger matches the task.
Load partner modules only for affected boundaries; never load the entire
ARCHITECTURE directory. Reuse unchanged pages already read in this session.
Check claims against source, configuration, and tests; they remain
authoritative. If a route or fact is missing or stale, inspect source and
repair the affected docs. For broad changes, work through owners in batches
and retain cross-owner constraints and verification evidence.
Project Snapshot
Fact
Value and evidence
Purpose
Binary emulation over Unicorn with images, OS APIs, hooks and firmware; entry is Qiling(...).run() (core). Complete OS/device fidelity is outside implemented scope.
Unicorn 2.1.3, Capstone ^5, Keystone ^0.9.2; other dependencies/platform extras in the manifest and lock.
Compatibility
Arch/OS enums in const.py, composition in utils.py; enums do not promise every combination. CI declares Python 3.11/3.13 on Ubuntu/Windows; macOS job is commented out.
System Design
Qiling.__init__ composes arch → hooks/packing → logging/profile → loader →
memory → OS → optional hardware, then runs the loader. run() applies
patches and delegates to the OS loop; Unicorn hooks enter Python dispatch.
Arch owns CPU/register state, memory owns mappings, loaders own image state,
and OS personalities own process/API state. Factory names are compatibility
contracts (core, factories).
Guest bytes/pointers cross host boundaries through loaders, memory, files
and sockets. Rootfs handling is not complete
host isolation; explicit mappings expose host objects. Snapshot files use
pickle and require trusted producers. The opt-in kernel proxy executes real
host syscalls. Follow the owners below for these contracts. Cooperative
scheduling and partial snapshots do not provide complete machine recovery.
Code Conventions
Required:.editorconfig sets Python UTF-8, LF, four
spaces, final newline and trailing-space removal. No formatter, linter or
type-checker gate is configured in the manifest/CI.
Observed:Ql* classes, snake_case helpers, uppercase constants;
legacy camelCase APIs and wildcard imports remain. Follow nearby code,
preserve public names, use ql.log and QlError* where established;
annotations are mixed (core, errors).
Preserved project rules: favor platform fidelity, keep API/peripheral
additions demand-driven, and treat Unicorn upgrades as project-wide work.
New top-level runtime dependencies require an explicit request; optional
integrations use extras. These strengthen shared review (prior project
architecture; current manifest). Keep dependencies toward
underlying services; read core before
changing cross-layer imports for the existing exceptions.
AGENT.md and CLAUDE.md alias this page; asset/fixture edit constraints
live with owners.
