appmem 0.1.0__tar.gz

appmem-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Damian Pala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

appmem-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: appmem
+Version: 0.1.0
+Summary: Live terminal view of RAM and swap usage per application, not per process
+Keywords: ram,swap,memory,cgroup,systemd,tui,monitoring,linux
+Author: Damian Pala
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Requires-Dist: textual>=8.2.8
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/DamianPala/appmem
+Project-URL: Repository, https://github.com/DamianPala/appmem
+Project-URL: Issues, https://github.com/DamianPala/appmem/issues
+Description-Content-Type: text/markdown
+
+# appmem
+
+Find out which apps are eating your RAM and swap. Live, in the terminal, one row per app.
+
+The laptop starts swapping, the fan spins up, and `htop` shows forty processes called `chrome`, thirty called `node` and something called `Isolated Web Co`.
+appmem shows the same memory as the apps you actually opened: Chrome, Firefox, VS Code, your terminal, each with its RAM, its swap and how much it grew since you started looking.
+The header tells you whether the swapping is a problem at all, and one key opens the processes behind any row.
+
+![appmem's main view: one row per app, sorted by TOTAL](https://raw.githubusercontent.com/DamianPala/appmem/main/docs/screenshots/main.svg)
+
+You can also skip the reading and hand the job to an AI agent.
+Paste this into Claude Code, Codex or any agent that runs shell commands:
+
+```
+Install appmem (uv tool install appmem), read
+https://raw.githubusercontent.com/DamianPala/appmem/main/skills/appmem/SKILL.md
+and tell me what is eating my memory and what to close.
+```
+
+It installs appmem, reads the numbers the way the skill file describes and tells you what to close.
+What the agent gets is in [For agents](#for-agents).
+
+Reach for it when:
+
+- the machine got slow and you want the culprit, not a process list;
+- swap is full and you want to know whether that matters right now;
+- a "terminal" holds 17 GiB and you want to know what is really running inside it;
+- you want to watch one app grow while you use it.
+
+## Install
+
+```
+uv tool install appmem
+appmem
+```
+
+No root, no config file.
+From a checkout, `uv run appmem`.
+
+You need Linux with systemd and a desktop that starts apps as systemd units (KDE Plasma and GNOME do), on cgroup v2, which current distributions use by default.
+Python 3.12 or newer; uv fetches it for you.
+Kernel 5.10 or newer; the zswap figures need 5.19 and the Pressure line needs pressure tracking (PSI) switched on in the kernel, without them those parts stay off and the rest works.
+
+## Using it
+
+The main view sorts by TOTAL (RAM + swap).
+Press the first letter of a column (`r`, `s`, `t`) or click a header to sort by something else.
+The Pressure figure in the header tells you whether memory is a problem right now: `none` with a full swap only means idle pages were moved out of the way, `some` or `high` means programs are waiting for memory.
+
+`Enter` on an app shows its processes, their age and the systemd unit each one lives in.
+The bottom line has the command ready for the selected row, for example `systemctl --user stop 'app-firefox.service'` or `kill 41233`.
+
+Everything you start from a terminal counts as the terminal.
+Press `g` in the process view to group by command.
+That is how a "terminal holding 17 GiB" turns out to be eighteen `claude` processes plus the terminal itself, running for 86 days with 3.4 GiB in swap.
+
+![The process view, grouped by command: several claude processes collapse into one row](https://raw.githubusercontent.com/DamianPala/appmem/main/docs/screenshots/processes.svg)
+
+ΔSWAP and ΔRAM show how each app grew or shrank since you started appmem (`b` resets the baseline).
+`x` adds system services, `c` shows the CACHE column.
+
+`T` opens a theme panel with a live preview: Textual's built-in themes plus `terminal-dark` and `terminal-light`, which use your terminal's own colours.
+The theme you keep is saved to `~/.config/appmem/config.toml`; `appmem --theme NAME` or `APPMEM_THEME` override it for one run.
+
+![The theme panel open on dracula, live-previewed on the main view behind it](https://raw.githubusercontent.com/DamianPala/appmem/main/docs/screenshots/theme-panel.svg)
+
+`?` inside the app explains every number and lists the keys; `appmem --help` has the same list plus the options.
+
+## How to read the numbers
+
+RAM is what the app is using right now.
+SWAP is what the system moved out of RAM to make room: onto the disk or, with zswap, into a compressed corner of RAM.
+TOTAL is RAM + SWAP, one number to sort by.
+Closing the app gives you back less than that: memory shared with other apps stays, and freed swap is mostly space on the disk, not RAM.
+CACHE (press `c`) is file data the kernel keeps around because something read or wrote it recently.
+It is not part of RAM or TOTAL: the kernel can drop it when it needs the space, and an app that just read a big file would otherwise look like a memory hog.
+The rows don't add up to the header, because system services, virtual machines, containers and other users hold the rest.
+
+## For agents
+
+appmem is made to be driven by an AI agent as much as by you; the prompt at the top is all it needs.
+The agent gets the same data as the TUI as JSON, and [skills/appmem/SKILL.md](https://github.com/DamianPala/appmem/blob/main/skills/appmem/SKILL.md) tells it how to read it: pressure against swap, what hides inside a terminal, what to recommend.
+
+```
+appmem snapshot [--system] [--limit N] [--json]
+appmem app NAME [--scope user|system] [--limit N] [--json]
+appmem schema [COMMAND]
+```
+
+`snapshot` covers the machine and every app, `app NAME` one app's units, processes and commands.
+Both print text on a terminal and JSON when piped; `--json` forces JSON.
+`appmem schema` describes the commands, flags, output fields and exit codes as JSON.
+Every error is one JSON object on the last line of stderr with a stable `kind` such as `not_found`; exit code 1 is a runtime failure, 2 an invalid call.
+Bare `appmem` without a terminal exits 1 and points to `appmem snapshot`.
+
+## Cost
+
+Reading the counters once a second takes about 1 % of one CPU core.
+The live view takes 4 to 12 % of one core on a busy desktop, more with a tall terminal and many apps.
+Refreshing every two seconds instead of every second (`appmem -i 2`) cuts that in half.
+
+## Development
+
+```
+uv run ruff check && uv run ruff format --check && uv run pyright && uv run pytest
+```
+
+The screenshots come from fixture data, never a real machine; regenerate them with `uv run python scripts/screenshots.py`.
+
+## License
+
+MIT

appmem-0.1.0/README.md

@@ -0,0 +1,112 @@
+# appmem
+
+Find out which apps are eating your RAM and swap. Live, in the terminal, one row per app.
+
+The laptop starts swapping, the fan spins up, and `htop` shows forty processes called `chrome`, thirty called `node` and something called `Isolated Web Co`.
+appmem shows the same memory as the apps you actually opened: Chrome, Firefox, VS Code, your terminal, each with its RAM, its swap and how much it grew since you started looking.
+The header tells you whether the swapping is a problem at all, and one key opens the processes behind any row.
+
+![appmem's main view: one row per app, sorted by TOTAL](https://raw.githubusercontent.com/DamianPala/appmem/main/docs/screenshots/main.svg)
+
+You can also skip the reading and hand the job to an AI agent.
+Paste this into Claude Code, Codex or any agent that runs shell commands:
+
+```
+Install appmem (uv tool install appmem), read
+https://raw.githubusercontent.com/DamianPala/appmem/main/skills/appmem/SKILL.md
+and tell me what is eating my memory and what to close.
+```
+
+It installs appmem, reads the numbers the way the skill file describes and tells you what to close.
+What the agent gets is in [For agents](#for-agents).
+
+Reach for it when:
+
+- the machine got slow and you want the culprit, not a process list;
+- swap is full and you want to know whether that matters right now;
+- a "terminal" holds 17 GiB and you want to know what is really running inside it;
+- you want to watch one app grow while you use it.
+
+## Install
+
+```
+uv tool install appmem
+appmem
+```
+
+No root, no config file.
+From a checkout, `uv run appmem`.
+
+You need Linux with systemd and a desktop that starts apps as systemd units (KDE Plasma and GNOME do), on cgroup v2, which current distributions use by default.
+Python 3.12 or newer; uv fetches it for you.
+Kernel 5.10 or newer; the zswap figures need 5.19 and the Pressure line needs pressure tracking (PSI) switched on in the kernel, without them those parts stay off and the rest works.
+
+## Using it
+
+The main view sorts by TOTAL (RAM + swap).
+Press the first letter of a column (`r`, `s`, `t`) or click a header to sort by something else.
+The Pressure figure in the header tells you whether memory is a problem right now: `none` with a full swap only means idle pages were moved out of the way, `some` or `high` means programs are waiting for memory.
+
+`Enter` on an app shows its processes, their age and the systemd unit each one lives in.
+The bottom line has the command ready for the selected row, for example `systemctl --user stop 'app-firefox.service'` or `kill 41233`.
+
+Everything you start from a terminal counts as the terminal.
+Press `g` in the process view to group by command.
+That is how a "terminal holding 17 GiB" turns out to be eighteen `claude` processes plus the terminal itself, running for 86 days with 3.4 GiB in swap.
+
+![The process view, grouped by command: several claude processes collapse into one row](https://raw.githubusercontent.com/DamianPala/appmem/main/docs/screenshots/processes.svg)
+
+ΔSWAP and ΔRAM show how each app grew or shrank since you started appmem (`b` resets the baseline).
+`x` adds system services, `c` shows the CACHE column.
+
+`T` opens a theme panel with a live preview: Textual's built-in themes plus `terminal-dark` and `terminal-light`, which use your terminal's own colours.
+The theme you keep is saved to `~/.config/appmem/config.toml`; `appmem --theme NAME` or `APPMEM_THEME` override it for one run.
+
+![The theme panel open on dracula, live-previewed on the main view behind it](https://raw.githubusercontent.com/DamianPala/appmem/main/docs/screenshots/theme-panel.svg)
+
+`?` inside the app explains every number and lists the keys; `appmem --help` has the same list plus the options.
+
+## How to read the numbers
+
+RAM is what the app is using right now.
+SWAP is what the system moved out of RAM to make room: onto the disk or, with zswap, into a compressed corner of RAM.
+TOTAL is RAM + SWAP, one number to sort by.
+Closing the app gives you back less than that: memory shared with other apps stays, and freed swap is mostly space on the disk, not RAM.
+CACHE (press `c`) is file data the kernel keeps around because something read or wrote it recently.
+It is not part of RAM or TOTAL: the kernel can drop it when it needs the space, and an app that just read a big file would otherwise look like a memory hog.
+The rows don't add up to the header, because system services, virtual machines, containers and other users hold the rest.
+
+## For agents
+
+appmem is made to be driven by an AI agent as much as by you; the prompt at the top is all it needs.
+The agent gets the same data as the TUI as JSON, and [skills/appmem/SKILL.md](https://github.com/DamianPala/appmem/blob/main/skills/appmem/SKILL.md) tells it how to read it: pressure against swap, what hides inside a terminal, what to recommend.
+
+```
+appmem snapshot [--system] [--limit N] [--json]
+appmem app NAME [--scope user|system] [--limit N] [--json]
+appmem schema [COMMAND]
+```
+
+`snapshot` covers the machine and every app, `app NAME` one app's units, processes and commands.
+Both print text on a terminal and JSON when piped; `--json` forces JSON.
+`appmem schema` describes the commands, flags, output fields and exit codes as JSON.
+Every error is one JSON object on the last line of stderr with a stable `kind` such as `not_found`; exit code 1 is a runtime failure, 2 an invalid call.
+Bare `appmem` without a terminal exits 1 and points to `appmem snapshot`.
+
+## Cost
+
+Reading the counters once a second takes about 1 % of one CPU core.
+The live view takes 4 to 12 % of one core on a busy desktop, more with a tall terminal and many apps.
+Refreshing every two seconds instead of every second (`appmem -i 2`) cuts that in half.
+
+## Development
+
+```
+uv run ruff check && uv run ruff format --check && uv run pyright && uv run pytest
+```
+
+The screenshots come from fixture data, never a real machine; regenerate them with `uv run python scripts/screenshots.py`.
+
+## License
+
+MIT

appmem-0.1.0/pyproject.toml

@@ -0,0 +1,119 @@
+[project]
+name = "appmem"
+version = "0.1.0"
+description = "Live terminal view of RAM and swap usage per application, not per process"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "ram",
+    "swap",
+    "memory",
+    "cgroup",
+    "systemd",
+    "tui",
+    "monitoring",
+    "linux",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Monitoring",
+]
+dependencies = ["textual>=8.2.8"]
+
+[[project.authors]]
+name = "Damian Pala"
+
+[project.urls]
+Homepage = "https://github.com/DamianPala/appmem"
+Repository = "https://github.com/DamianPala/appmem"
+Issues = "https://github.com/DamianPala/appmem/issues"
+
+[project.scripts]
+appmem = "appmem.__main__:main"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1",
+    "pytest>=8",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.14",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.10,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = [
+    "src",
+    "tests",
+    "scripts",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "W",
+    "N",
+    "UP",
+    "B",
+    "C4",
+    "SIM",
+    "RUF",
+    "C90",
+    "PLR0913",
+    "PLR0917",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 8
+
+[tool.ruff.lint.pylint]
+max-args = 8
+max-positional-args = 5
+
+[tool.ruff.lint.isort]
+known-first-party = ["appmem"]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/*" = ["E402"]
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+include = [
+    "src",
+    "tests",
+    "scripts",
+]
+venvPath = "."
+venv = ".venv"
+
+[[tool.pyright.executionEnvironments]]
+root = "scripts"
+extraPaths = [
+    "tests",
+    "src",
+]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --strict-config"
+testpaths = ["tests"]
+filterwarnings = ["error"]
+asyncio_mode = "strict"
+
+[tool.uv]
+exclude-newer = "2026-09-25T00:00:00Z"

appmem-0.1.0/pyproject.toml.orig

@@ -0,0 +1,89 @@
+[project]
+name = "appmem"
+version = "0.1.0"
+description = "Live terminal view of RAM and swap usage per application, not per process"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Damian Pala" }]
+keywords = ["ram", "swap", "memory", "cgroup", "systemd", "tui", "monitoring", "linux"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "textual>=8.2.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/DamianPala/appmem"
+Repository = "https://github.com/DamianPala/appmem"
+Issues = "https://github.com/DamianPala/appmem/issues"
+
+[project.scripts]
+appmem = "appmem.__main__:main"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1",
+    "pytest>=8",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.14",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.10,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests", "scripts"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "N", "UP", "B", "C4", "SIM", "RUF", "C90", "PLR0913", "PLR0917"]
+mccabe.max-complexity = 8
+pylint.max-args = 8
+pylint.max-positional-args = 5
+
+[tool.ruff.lint.isort]
+known-first-party = ["appmem"]
+
+[tool.ruff.lint.per-file-ignores]
+# scripts/screenshots.py fixes `sys.path` to reach tests/helpers.py before
+# importing from it -- see the comment at that import.
+"scripts/*" = ["E402"]
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+include = ["src", "tests", "scripts"]
+venvPath = "."
+venv = ".venv"
+
+[[tool.pyright.executionEnvironments]]
+# Only scripts/ needs tests/helpers.py on its path (see the comment at that
+# import in scripts/screenshots.py); scoping it here, instead of a top-level
+# extraPaths, keeps pyright resolving the installed `appmem` package for
+# src/ and tests/ exactly as before.
+root = "scripts"
+extraPaths = ["tests", "src"]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --strict-config"
+testpaths = ["tests"]
+filterwarnings = ["error"]
+asyncio_mode = "strict"
+
+[tool.uv]
+# Pinned so `uv lock` resolves the same set everywhere; a user-level `exclude-newer`
+# alone is not recorded consistently and made CI's `uv sync --locked` re-resolve.
+exclude-newer = "2026-09-25T00:00:00Z"

appmem-0.1.0/src/appmem/__init__.py

@@ -0,0 +1,7 @@
+"""appmem: live terminal view of RAM and swap usage per application."""
+
+from importlib.metadata import version
+
+# pyproject.toml's [project] version is the single source; read it back from the
+# installed distribution's metadata instead of duplicating it here by hand.
+__version__ = version(__name__)

appmem-0.1.0/src/appmem/__main__.py

@@ -0,0 +1,14 @@
+"""CLI entry point (SPEC.md "Command line")."""
+
+from __future__ import annotations
+
+from appmem.cli import main as _main
+
+
+def main() -> None:
+    """Run the CLI and exit with its process exit code."""
+    raise SystemExit(_main())
+
+
+if __name__ == "__main__":
+    main()