focus-now 0.1.0__tar.gz

focus_now-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.3
+Name: focus-now
+Version: 0.1.0
+Summary: Add your description here
+Author: Ian Atroshchenko
+Author-email: Ian Atroshchenko <ianatroshchenko@gmail.com>
+Requires-Dist: anthropic>=1.11.0
+Requires-Dist: mss>=10.2.0
+Requires-Dist: openai>=3.23.0
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: pyfiglet>=1.0.4
+Requires-Dist: python-xlib>=0.33 ; sys_platform == 'linux'
+Requires-Dist: typer>=0.27.2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+

focus_now-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "focus-now"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "anthropic>=1.11.0",
+    "mss>=10.2.0",
+    "openai>=3.23.0",
+    "pillow>=12.3.0",
+    "psutil>=7.2.2",
+    "pyfiglet>=1.0.4",
+    "python-xlib>=0.33 ; sys_platform == 'linux'",
+    "typer>=0.27.2",
+]
+
+[[project.authors]]
+name = "Ian Atroshchenko"
+email = "ianatroshchenko@gmail.com"
+
+[project.scripts]
+focus = "focus.main:app"
+
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "focus"

focus_now-0.1.0/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "focus-now"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Ian Atroshchenko", email = "ianatroshchenko@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "anthropic>=1.11.0",
+    "mss>=10.2.0",
+    "openai>=3.23.0",
+    "pillow>=12.3.0",
+    "psutil>=7.2.2",
+    "pyfiglet>=1.0.4",
+    "python-xlib>=0.33 ; sys_platform == 'linux'",
+    "typer>=0.27.2",
+]
+
+[project.scripts]
+focus = "focus.main:app"
+
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "focus"
+

focus_now-0.1.0/src/focus/agent/agent.py

@@ -0,0 +1,331 @@
+import json
+import time
+from abc import ABC, abstractmethod
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+import anthropic
+import openai
+
+from focus.tools import TOOLS, Screenshot, ToolResult, run_tool
+from focus.utils.log import err, log, warn
+from focus.utils.prompts import build_system_prompt, check_in
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    args: dict[str, Any]
+    # set when the model's arguments couldn't be parsed; the call is reported back, not run
+    error: str | None = None
+
+
+@dataclass
+class Turn:
+    """one model response, normalized across providers"""
+
+    text: str
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    stopped_early: str | None = None
+
+
+class BaseAgent(ABC):
+    DEFAULT_MODEL: str
+    # API errors that retrying won't fix: bad key, unknown model, malformed request
+    FATAL_ERRORS: tuple[type[Exception], ...] = ()
+
+    def __init__(
+        self,
+        model: str,
+        api_key: str,
+        task: str | None = None,
+        interval: float = 20.0,
+        effort: str | None = "low",
+        max_turns: int = 10,
+        max_notes: int = 12,
+    ):
+        self.model = model
+        self.api_key = api_key
+        self.system_prompt = build_system_prompt(task)
+        self.interval = interval
+        self.effort = effort
+        self.max_turns = max_turns
+        self.notes: deque[str] = deque(maxlen=max_notes)
+        self.started_at = time.time()
+
+    @abstractmethod
+    def _user_message(self, text: str, images: list[Screenshot]) -> list[Any]:
+        """conversation items for a user message"""
+
+    @abstractmethod
+    def _complete(self, conversation: list[Any]) -> Turn:
+        """call the model, append its output to the conversation, and parse the turn"""
+
+    @abstractmethod
+    def _tool_results(self, results: list[tuple[ToolCall, ToolResult]]) -> list[Any]:
+        """conversation items reporting tool results back to the model"""
+
+    def capture_screen(self) -> ToolResult:
+        return run_tool("capture_screen", {})
+
+    def use_tool(self, call: ToolCall) -> ToolResult:
+        if call.error:
+            result = ToolResult(call.error, is_error=True)
+        else:
+            result = run_tool(call.name, call.args)
+
+        args = ", ".join(f"{k}={v!r}" for k, v in call.args.items())
+        line = f"[cyan]{call.name}[/cyan]({args})"
+        if result.is_error:
+            warn(f"{line} -> {result.text}")
+        else:
+            log(line)
+        return result
+
+    def prompt(self, text: str, images: list[Screenshot] | None = None) -> str:
+        """send the model a prompt and let it use tools until it's done. returns its final text"""
+        conversation = self._user_message(text, images or [])
+
+        for _ in range(self.max_turns):
+            turn = self._complete(conversation)
+            if turn.stopped_early:
+                warn(turn.stopped_early)
+            if turn.stopped_early or not turn.tool_calls:
+                return turn.text
+
+            results = [(call, self.use_tool(call)) for call in turn.tool_calls]
+            conversation.extend(self._tool_results(results))
+
+        warn(f"check-in hit the {self.max_turns} turn limit")
+        return turn.text
+
+    def check_in(self) -> str:
+        notes = "\n".join(f"- {note}" for note in self.notes)
+        text = check_in.format(
+            time=time.strftime("%H:%M:%S"),
+            elapsed=_format_duration(time.time() - self.started_at),
+            notes=notes or "(none yet, this is the first check-in)",
+        )
+        screen = self.capture_screen()
+        if screen.is_error:
+            text += f"\n\n(automatic screenshot failed: {screen.text})"
+
+        summary = self.prompt(text, screen.images).strip()
+        if summary:
+            # the model's closing line is its memory for the next check-in
+            self.notes.append(f"{time.strftime('%H:%M')} {summary.splitlines()[-1]}")
+            log(summary)
+        return summary
+
+    def run(self) -> None:
+        log(f"monitoring every {self.interval:g}s with {self.model}. ctrl+c to stop")
+        try:
+            while True:
+                try:
+                    self.check_in()
+                except self.FATAL_ERRORS as e:
+                    err(f"{type(e).__name__}: {e}")
+                except Exception as e:
+                    warn(f"check-in failed, retrying next interval: {type(e).__name__}: {e}")
+                time.sleep(self.interval)
+        except KeyboardInterrupt:
+            log("focus session ended. nice work :)")
+
+
+class AnthropicAgent(BaseAgent):
+    DEFAULT_MODEL = "claude-sonnet-5-5"
+    FATAL_ERRORS = (
+        anthropic.AuthenticationError,
+        anthropic.PermissionDeniedError,
+        anthropic.NotFoundError,
+        anthropic.BadRequestError,
+    )
+    # models that accept the server-side refusal fallback. screen contents are
+    # arbitrary, so a safety decline on one frame shouldn't end the check-in
+    FALLBACK_MODELS = {"claude-fable-5-1", "claude-opus-5-5", "claude-opus-5", "claude-sonnet-5-5"}
+    MAX_TOKENS = 16000
+
+    def __init__(self, model: str = DEFAULT_MODEL, **kwargs):
+        super().__init__(model=model, **kwargs)
+        self.client = anthropic.Anthropic(api_key=self.api_key)
+        self.tools = [
+            {"name": t.name, "description": t.description, "input_schema": t.parameters}
+            for t in TOOLS
+        ]
+
+        self.request_options: dict[str, Any] = {}
+        if self.effort and not model.startswith("claude-haiku"):
+            self.request_options["output_config"] = {"effort": self.effort}
+
+        self.create_message = self.client.messages.create
+        if model in self.FALLBACK_MODELS:
+            self.create_message = self.client.beta.messages.create
+            self.request_options |= {
+                "betas": ["server-side-fallback-2026-07-01"],
+                "fallbacks": "default",
+            }
+
+    def _user_message(self, text, images):
+        content = [self._image(shot) for shot in images]
+        content.append({"type": "text", "text": text})
+        return [{"role": "user", "content": content}]
+
+    def _complete(self, conversation):
+        response = self.create_message(
+            model=self.model,
+            max_tokens=self.MAX_TOKENS,
+            # system and tools never change, so this prefix stays cached across check-ins;
+            # the top-level cache_control caches the growing conversation within one
+            system=[
+                {"type": "text", "text": self.system_prompt, "cache_control": {"type": "ephemeral"}}
+            ],
+            cache_control={"type": "ephemeral"},
+            tools=self.tools,
+            messages=conversation,
+            **self.request_options,
+        )
+        # append the content unchanged; thinking and fallback blocks must be sent back as-is
+        conversation.append({"role": "assistant", "content": response.content})
+
+        return Turn(
+            text="\n".join(b.text for b in response.content if b.type == "text"),
+            tool_calls=[
+                ToolCall(b.id, b.name, dict(b.input))
+                for b in response.content
+                if b.type == "tool_use"
+            ],
+            stopped_early={
+                "refusal": "the model declined to review this screen",
+                "max_tokens": "the model ran out of output tokens mid-check-in",
+            }.get(response.stop_reason),
+        )
+
+    def _tool_results(self, results):
+        blocks = [
+            {
+                "type": "tool_result",
+                "tool_use_id": call.id,
+                "content": [
+                    {"type": "text", "text": result.text},
+                    *(self._image(shot) for shot in result.images),
+                ],
+                "is_error": result.is_error,
+            }
+            for call, result in results
+        ]
+        # every result for a turn goes back in one user message
+        return [{"role": "user", "content": blocks}]
+
+    @staticmethod
+    def _image(shot: Screenshot) -> dict[str, Any]:
+        return {
+            "type": "image",
+            "source": {"type": "base64", "media_type": shot.media_type, "data": shot.b64},
+        }
+
+
+class OpenAIAgent(BaseAgent):
+    DEFAULT_MODEL = "gpt-5"
+    FATAL_ERRORS = (
+        openai.AuthenticationError,
+        openai.PermissionDeniedError,
+        openai.NotFoundError,
+        openai.BadRequestError,
+    )
+
+    def __init__(self, model: str = DEFAULT_MODEL, **kwargs):
+        super().__init__(model=model, **kwargs)
+        self.client = openai.OpenAI(api_key=self.api_key)
+        self.tools = [
+            {
+                "type": "function",
+                "name": t.name,
+                "description": t.description,
+                "parameters": t.parameters,
+                "strict": False,
+            }
+            for t in TOOLS
+        ]
+
+        self.request_options: dict[str, Any] = {}
+        if not model.startswith(("gpt-4", "gpt-3")):
+            # with store=False, reasoning carries over between turns as encrypted items
+            self.request_options["include"] = ["reasoning.encrypted_content"]
+            if self.effort:
+                self.request_options["reasoning"] = {"effort": self.effort}
+
+    def _user_message(self, text, images):
+        content = [self._image(shot) for shot in images]
+        content.append({"type": "input_text", "text": text})
+        return [{"role": "user", "content": content}]
+
+    def _complete(self, conversation):
+        response = self.client.responses.create(
+            model=self.model,
+            instructions=self.system_prompt,
+            input=conversation,
+            tools=self.tools,
+            # screenshots are private, so nothing is kept server side
+            store=False,
+            **self.request_options,
+        )
+        conversation.extend(response.output)
+
+        stopped_early = None
+        if response.status == "incomplete":
+            reason = getattr(response.incomplete_details, "reason", "unknown")
+            stopped_early = f"the model stopped early ({reason})"
+
+        return Turn(
+            text=response.output_text,
+            tool_calls=[
+                self._parse_call(item) for item in response.output if item.type == "function_call"
+            ],
+            stopped_early=stopped_early,
+        )
+
+    def _tool_results(self, results):
+        return [
+            {"type": "function_call_output", "call_id": call.id, "output": self._output(result)}
+            for call, result in results
+        ]
+
+    @staticmethod
+    def _parse_call(item) -> ToolCall:
+        try:
+            return ToolCall(item.call_id, item.name, json.loads(item.arguments or "{}"))
+        except json.JSONDecodeError:
+            return ToolCall(item.call_id, item.name, {}, error="tool arguments were not valid JSON")
+
+    @classmethod
+    def _output(cls, result: ToolResult) -> str | list[dict[str, Any]]:
+        text = f"error: {result.text}" if result.is_error else result.text
+        if not result.images:
+            return text
+        return [{"type": "input_text", "text": text}, *map(cls._image, result.images)]
+
+    @staticmethod
+    def _image(shot: Screenshot) -> dict[str, Any]:
+        return {"type": "input_image", "image_url": shot.data_url, "detail": "high"}
+
+
+AGENTS: dict[str, type[BaseAgent]] = {
+    "anthropic": AnthropicAgent,
+    "openai": OpenAIAgent,
+}
+DEFAULT_MODELS = {provider: agent.DEFAULT_MODEL for provider, agent in AGENTS.items()}
+
+
+def create_agent(provider: str, model: str | None = None, **kwargs) -> BaseAgent:
+    if provider not in AGENTS:
+        err(f"unknown provider '{provider}'. choose one of: {', '.join(AGENTS)}")
+    agent = AGENTS[provider]
+    return agent(model=model or agent.DEFAULT_MODEL, **kwargs)
+
+
+def _format_duration(seconds: float) -> str:
+    minutes, seconds = divmod(int(seconds), 60)
+    hours, minutes = divmod(minutes, 60)
+    return f"{hours}h {minutes}m" if hours else f"{minutes}m {seconds}s"

focus_now-0.1.0/src/focus/main.py

@@ -0,0 +1,62 @@
+import typer
+from focus.agent.agent import DEFAULT_MODELS, create_agent
+from focus.utils.log import warn, err, log
+
+import os
+from pyfiglet import figlet_format
+
+app = typer.Typer()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    key: str | None = typer.Option(None, "--key", help="api key to use for Focus"),
+    provider: str = typer.Option(
+        "anthropic", "--provider", help="model provider to use for Focus (anthropic, openai)"
+    ),
+    model: str | None = typer.Option(
+        None,
+        "--model",
+        help=f"model type to use for Focus (defaults: {', '.join(f'{p}={m}' for p, m in DEFAULT_MODELS.items())})",
+    ),
+    task: str | None = typer.Option(
+        None,
+        "--task",
+        help="task you wish to complete in this Focus session. without one, Focus keeps you on generally productive work",
+    ),
+    interval: float = typer.Option(
+        20.0, "--interval", help="seconds to wait between screen check-ins"
+    ),
+    effort: str = typer.Option(
+        "low", "--effort", help="how hard the model thinks per check-in (low, medium, high)"
+    ),
+):
+    if ctx.invoked_subcommand is None:
+        start_focus(provider, model, key, task, interval, effort)
+
+
+def start_focus(
+    provider: str,
+    model: str | None,
+    key: str | None = None,
+    task: str | None = None,
+    interval: float = 20.0,
+    effort: str = "low",
+):
+    if key == None:
+        warn("provider api key not given. searching...")
+        key = os.getenv(provider.upper() + "_API_KEY")
+
+        if key == None:
+            err(
+                "provider api key not found. please set $OPENAI_API_KEY, $ANTHROPIC_API_KEY, or pass in api_key with the [green]--key[/green] argument"
+            )
+
+    f = figlet_format("FOCUS!", font="slant")
+    print(f)
+    agent = create_agent(
+        provider, model, api_key=key, task=task, interval=interval, effort=effort
+    )
+    log("focus is now running :)")
+    agent.run()

focus_now-0.1.0/src/focus/tools/__init__.py

@@ -0,0 +1,4 @@
+from focus.tools.base import Screenshot, Tool, ToolResult
+from focus.tools.definitions import TOOLS, run_tool
+
+__all__ = ["TOOLS", "Screenshot", "Tool", "ToolResult", "run_tool"]

focus_now-0.1.0/src/focus/tools/base.py

@@ -0,0 +1,70 @@
+import base64
+import io
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from PIL import Image
+
+# providers downscale anything larger, so bigger images only cost bandwidth and tokens
+MAX_IMAGE_EDGE = 1568
+JPEG_QUALITY = 75
+
+
+@dataclass
+class Screenshot:
+    data: bytes
+    media_type: str
+    width: int
+    height: int
+    label: str = ""
+
+    @classmethod
+    def from_image(cls, image: Image.Image, label: str = "") -> "Screenshot":
+        image.thumbnail((MAX_IMAGE_EDGE, MAX_IMAGE_EDGE))
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+        buffer = io.BytesIO()
+        image.save(buffer, format="JPEG", quality=JPEG_QUALITY)
+        return cls(buffer.getvalue(), "image/jpeg", image.width, image.height, label)
+
+    @property
+    def b64(self) -> str:
+        return base64.standard_b64encode(self.data).decode("ascii")
+
+    @property
+    def data_url(self) -> str:
+        return f"data:{self.media_type};base64,{self.b64}"
+
+
+@dataclass
+class ToolResult:
+    text: str
+    images: list[Screenshot] = field(default_factory=list)
+    is_error: bool = False
+
+
+@dataclass
+class Tool:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    handler: Callable[..., ToolResult]
+
+
+def tool(description: str, parameters: dict[str, Any] | None = None):
+    """turn a handler function into a model-facing Tool named after the function"""
+
+    def wrap(handler: Callable[..., ToolResult]) -> Tool:
+        return Tool(handler.__name__, description, parameters or schema(), handler)
+
+    return wrap
+
+
+def schema(required: tuple[str, ...] = (), **properties: dict[str, Any]) -> dict[str, Any]:
+    """JSON schema for a tool's arguments"""
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": list(required),
+        "additionalProperties": False,
+    }

focus_now-0.1.0/src/focus/tools/definitions.py

@@ -0,0 +1,149 @@
+import time
+from typing import Any
+
+from focus.tools.base import Screenshot, Tool, ToolResult, schema, tool
+from focus.tools.platform import PlatformError, get_platform
+
+MAX_WAIT_SECONDS = 60
+
+
+@tool(
+    "Take a screenshot of every monitor and return the images. This is your primary way "
+    "of seeing what the user is doing. Call it again after any action (closing a tab, "
+    "killing an app) to confirm the result."
+)
+def capture_screen() -> ToolResult:
+    shots = [
+        Screenshot.from_image(image, label=f"monitor {i}")
+        for i, image in enumerate(get_platform().grab_screens(), start=1)
+    ]
+    sizes = ", ".join(f"{s.label}: {s.width}x{s.height}" for s in shots)
+    return ToolResult(
+        f"captured {len(shots)} screen(s) at {time.strftime('%H:%M:%S')} ({sizes})",
+        images=shots,
+    )
+
+
+@tool(
+    "List the user's open windows with their window id, app name, process id, and title. "
+    "The focused window is marked with '*'. Browser window titles usually contain the "
+    "active tab's page title, which helps tell productive browsing from distraction. Use "
+    "the ids/pids/app names here for close_tab and kill_app."
+)
+def list_windows() -> ToolResult:
+    windows = get_platform().list_windows()
+    if not windows:
+        return ToolResult("no open windows found")
+
+    lines = [
+        f"{'*' if w.focused else ' '} id={w.id} app={w.app} pid={w.pid} title={w.title!r}"
+        for w in windows
+    ]
+    return ToolResult("open windows (* = focused):\n" + "\n".join(lines))
+
+
+@tool(
+    "Show the user a desktop notification. This is the gentlest intervention: use it "
+    "first to nudge the user back on task before taking stronger action. Keep messages "
+    "short, specific, and friendly.",
+    schema(
+        required=("title", "message"),
+        title={"type": "string", "description": "short notification title"},
+        message={"type": "string", "description": "notification body, one or two sentences"},
+        urgency={
+            "type": "string",
+            "enum": ["low", "normal", "critical"],
+            "description": "critical notifications stay on screen until dismissed",
+        },
+    ),
+)
+def notify_user(title: str, message: str, urgency: str = "normal") -> ToolResult:
+    get_platform().notify(title, message, urgency)
+    return ToolResult(f"notification shown: {title!r}")
+
+
+@tool(
+    "Close the active tab of a browser (or other tabbed app) by focusing the window and "
+    "pressing the close-tab keyboard shortcut. Only use this when the distracting content "
+    "is the ACTIVE tab of that window, as seen in a screenshot or the window title. In "
+    "non-tabbed apps the same shortcut may close the whole window or document, so don't "
+    "use it there.",
+    schema(
+        window_id={
+            "type": "string",
+            "description": "window id from list_windows. omit to target the focused window",
+        },
+    ),
+)
+def close_tab(window_id: str | None = None) -> ToolResult:
+    get_platform().close_tab(window_id)
+    target = f"window {window_id}" if window_id else "the focused window"
+    return ToolResult(
+        f"sent the close-tab shortcut to {target}. capture the screen to confirm it worked."
+    )
+
+
+@tool(
+    "Terminate an application by process name (kills every process with that exact name, "
+    "e.g. 'Discord') or by pid. This is the strongest intervention; reserve it for clear, "
+    "repeated distraction after the user has already been warned. System processes, Focus "
+    "itself, and the terminal it runs in are protected and will be refused.",
+    schema(
+        name={"type": "string", "description": "exact process name, case-insensitive"},
+        pid={"type": "integer", "description": "a specific process id"},
+    ),
+)
+def kill_app(name: str | None = None, pid: int | None = None) -> ToolResult:
+    report = get_platform().kill_app(name=name, pid=pid)
+    if not report.killed and not report.refused:
+        return ToolResult(
+            f"no running process matched {name or pid}. "
+            "use list_windows to find the right app name or pid.",
+            is_error=True,
+        )
+
+    lines = []
+    if report.killed:
+        lines.append("killed: " + ", ".join(report.killed))
+    if report.refused:
+        lines.append(
+            "refused (protected system process, Focus itself, or another user's): "
+            + ", ".join(report.refused)
+        )
+    return ToolResult("\n".join(lines), is_error=not report.killed)
+
+
+@tool(
+    f"Pause for a few seconds (1-{MAX_WAIT_SECONDS}) before looking again. Use this when "
+    "you suspect distraction but aren't sure yet, e.g. the user might be briefly checking "
+    "a message or looking something up, then capture_screen again to see whether it "
+    "continued.",
+    schema(
+        required=("seconds",),
+        seconds={"type": "number", "minimum": 1, "maximum": MAX_WAIT_SECONDS},
+    ),
+)
+def wait(seconds: float) -> ToolResult:
+    seconds = max(1.0, min(float(seconds), MAX_WAIT_SECONDS))
+    time.sleep(seconds)
+    return ToolResult(f"waited {seconds:g} seconds")
+
+
+TOOLS: list[Tool] = [capture_screen, list_windows, notify_user, close_tab, kill_app, wait]
+TOOLS_BY_NAME: dict[str, Tool] = {t.name: t for t in TOOLS}
+
+
+def run_tool(name: str, args: dict[str, Any]) -> ToolResult:
+    """run a tool call from any provider. failures become error results the model can
+    read and react to, rather than exceptions that end the check-in"""
+    if name not in TOOLS_BY_NAME:
+        return ToolResult(f"unknown tool: {name}", is_error=True)
+
+    try:
+        return TOOLS_BY_NAME[name].handler(**args)
+    except PlatformError as e:
+        return ToolResult(str(e), is_error=True)
+    except TypeError as e:
+        return ToolResult(f"bad arguments for {name}: {e}", is_error=True)
+    except Exception as e:
+        return ToolResult(f"{name} failed: {type(e).__name__}: {e}", is_error=True)

focus_now-0.1.0/src/focus/tools/platform/__init__.py

@@ -0,0 +1,40 @@
+import os
+import sys
+from functools import cache
+
+from focus.tools.platform.base import (
+    KillReport,
+    Platform,
+    PlatformError,
+    UnsupportedPlatform,
+    WindowInfo,
+)
+
+
+@cache
+def get_platform() -> Platform:
+    """the Platform implementation for the OS and display server Focus is running on"""
+    if sys.platform.startswith("linux"):
+        if os.environ.get("WAYLAND_DISPLAY") or os.environ.get("XDG_SESSION_TYPE") == "wayland":
+            from focus.tools.platform.linux import WaylandPlatform
+
+            return WaylandPlatform()
+
+        from focus.tools.platform.linux import X11Platform
+
+        return X11Platform()
+
+    if sys.platform == "darwin":
+        from focus.tools.platform.macos import MacOSPlatform
+
+        return MacOSPlatform()
+
+    if sys.platform == "win32":
+        from focus.tools.platform.windows import WindowsPlatform
+
+        return WindowsPlatform()
+
+    return UnsupportedPlatform(sys.platform)
+
+
+__all__ = ["get_platform", "KillReport", "Platform", "PlatformError", "WindowInfo"]

focus_now-0.1.0/src/focus/tools/platform/base.py

@@ -0,0 +1,118 @@
+from abc import ABC, abstractmethod
+from contextlib import suppress
+from dataclasses import dataclass
+
+import psutil
+from PIL import Image
+
+
+class PlatformError(Exception):
+    """raised when the OS can't do what was asked (missing utility, no display, ...)"""
+
+
+@dataclass
+class WindowInfo:
+    id: str
+    title: str
+    app: str
+    pid: int | None
+    focused: bool = False
+
+
+@dataclass
+class KillReport:
+    killed: list[str]
+    refused: list[str]
+
+
+class Platform(ABC):
+    name: str = "unknown"
+
+    # process names Focus must never kill, whatever the model asks. each OS fills this in
+    protected_processes: frozenset[str] = frozenset()
+
+    @abstractmethod
+    def grab_screens(self) -> list[Image.Image]:
+        """one image per monitor"""
+
+    @abstractmethod
+    def list_windows(self) -> list[WindowInfo]:
+        """open top-level windows, with the focused one marked"""
+
+    @abstractmethod
+    def notify(self, title: str, message: str, urgency: str = "normal") -> None:
+        """show a system notification. urgency is one of low/normal/critical"""
+
+    @abstractmethod
+    def focus_window(self, window_id: str) -> None:
+        """raise and focus a window by the id returned from list_windows"""
+
+    @abstractmethod
+    def send_close_tab_shortcut(self) -> None:
+        """press the OS's close-tab shortcut (ctrl+w, cmd+w, ...) in the focused window"""
+
+    def close_tab(self, window_id: str | None = None) -> None:
+        if window_id is not None:
+            self.focus_window(window_id)
+        self.send_close_tab_shortcut()
+
+    def kill_app(self, name: str | None = None, pid: int | None = None) -> KillReport:
+        if name is None and pid is None:
+            raise PlatformError("give either an app name or a pid")
+
+        me = psutil.Process()
+        user = me.username()
+        protected_pids = {me.pid, *(parent.pid for parent in me.parents())}
+        targets, refused = [], []
+
+        for proc in psutil.process_iter(["pid", "name", "username"]):
+            proc_pid, proc_name = proc.info["pid"], (proc.info["name"] or "").lower()
+            matches = proc_pid == pid or (name is not None and proc_name == name.lower())
+            if not matches:
+                continue
+
+            is_protected = (
+                proc_pid in protected_pids
+                or proc_name in self.protected_processes
+                or proc.info["username"] != user
+            )
+            (refused if is_protected else targets).append(proc)
+
+        for proc in targets:
+            with suppress(psutil.NoSuchProcess):
+                proc.terminate()
+        _, still_alive = psutil.wait_procs(targets, timeout=3)
+        for proc in still_alive:
+            with suppress(psutil.NoSuchProcess):
+                proc.kill()
+
+        return KillReport(killed=_labels(targets), refused=_labels(refused))
+
+
+class UnsupportedPlatform(Platform):
+    """placeholder for OSes that don't have an implementation yet"""
+
+    def __init__(self, os_name: str):
+        self.name = os_name
+
+    def _unsupported(self):
+        raise PlatformError(f"{self.name} is not supported by Focus yet")
+
+    def grab_screens(self):
+        self._unsupported()
+
+    def list_windows(self):
+        self._unsupported()
+
+    def notify(self, title, message, urgency="normal"):
+        self._unsupported()
+
+    def focus_window(self, window_id):
+        self._unsupported()
+
+    def send_close_tab_shortcut(self):
+        self._unsupported()
+
+
+def _labels(procs: list[psutil.Process]) -> list[str]:
+    return [f"{p.info['name']} (pid {p.info['pid']})" for p in procs]

focus_now-0.1.0/src/focus/tools/platform/linux.py

@@ -0,0 +1,157 @@
+import io
+import shutil
+import subprocess
+import time
+
+import mss
+from PIL import Image
+from Xlib import XK, X, display
+from Xlib.error import XError
+from Xlib.ext import xtest
+from Xlib.protocol import event
+
+from focus.tools.platform.base import Platform, PlatformError, WindowInfo
+
+
+class LinuxPlatform(Platform):
+    """behaviour shared by every linux display server"""
+
+    name = "linux"
+
+    protected_processes = frozenset(
+        # core system services
+        "systemd init xorg x xwayland dbus-daemon dbus-broker sshd login sddm gdm lightdm "
+        "pipewire pipewire-pulse wireplumber pulseaudio "
+        # window managers, compositors, desktop shells and bars
+        "i3 i3bar sway hyprland gnome-shell kwin_x11 kwin_wayland plasmashell xfwm4 "
+        "openbox bspwm awesome polybar waybar".split()
+    )
+
+    def notify(self, title: str, message: str, urgency: str = "normal") -> None:
+        self._require("notify-send", "notifications need `notify-send` (libnotify)")
+        self._run("notify-send", "-a", "Focus", "-u", urgency, title, message)
+
+    @staticmethod
+    def _require(command: str, reason: str) -> None:
+        if not shutil.which(command):
+            raise PlatformError(f"{reason} installed")
+
+    @staticmethod
+    def _run(*cmd: str) -> bytes:
+        try:
+            return subprocess.run(cmd, check=True, capture_output=True, timeout=10).stdout
+        except subprocess.CalledProcessError as e:
+            stderr = e.stderr.decode(errors="replace").strip()
+            raise PlatformError(f"`{cmd[0]}` failed: {stderr}") from e
+        except subprocess.TimeoutExpired as e:
+            raise PlatformError(f"`{cmd[0]}` timed out") from e
+
+
+class X11Platform(LinuxPlatform):
+    """screenshots via mss, window management via EWMH, keystrokes via XTest"""
+
+    def __init__(self):
+        try:
+            self._display = display.Display()
+            self._screen_grabber = mss.MSS()
+        except Exception as e:
+            raise PlatformError(f"couldn't connect to the X server: {e}") from e
+        self._root = self._display.screen().root
+
+    def grab_screens(self) -> list[Image.Image]:
+        # monitors[0] is every monitor combined; the rest are the individual monitors
+        monitors = self._screen_grabber.monitors
+        return [
+            Image.frombytes("RGB", shot.size, shot.rgb)
+            for shot in map(self._screen_grabber.grab, monitors[1:] or monitors[:1])
+        ]
+
+    def list_windows(self) -> list[WindowInfo]:
+        client_ids = self._root_property("_NET_CLIENT_LIST")
+        active_ids = self._root_property("_NET_ACTIVE_WINDOW")
+        active_id = active_ids[0] if active_ids else None
+
+        windows = []
+        for window_id in client_ids:
+            try:
+                windows.append(self._window_info(window_id, focused=window_id == active_id))
+            except XError:
+                # the window closed between listing and inspecting it
+                continue
+        return windows
+
+    def focus_window(self, window_id: str) -> None:
+        window = self._display.create_resource_object("window", int(window_id, 16))
+        # source indication 2 ("pager") is honoured more readily by window managers
+        request = event.ClientMessage(
+            window=window,
+            client_type=self._atom("_NET_ACTIVE_WINDOW"),
+            data=(32, [2, X.CurrentTime, 0, 0, 0]),
+        )
+        self._root.send_event(
+            request, event_mask=X.SubstructureRedirectMask | X.SubstructureNotifyMask
+        )
+        self._display.sync()
+        # let the window manager finish switching before keys are sent to the window
+        time.sleep(0.25)
+
+    def send_close_tab_shortcut(self) -> None:
+        ctrl = self._display.keysym_to_keycode(XK.XK_Control_L)
+        w = self._display.keysym_to_keycode(XK.string_to_keysym("w"))
+        for event_type, key in [
+            (X.KeyPress, ctrl),
+            (X.KeyPress, w),
+            (X.KeyRelease, w),
+            (X.KeyRelease, ctrl),
+        ]:
+            xtest.fake_input(self._display, event_type, key)
+        self._display.sync()
+
+    def _window_info(self, window_id: int, focused: bool) -> WindowInfo:
+        window = self._display.create_resource_object("window", window_id)
+        title = window.get_full_text_property(
+            self._atom("_NET_WM_NAME"), self._atom("UTF8_STRING")
+        )
+        wm_class = window.get_wm_class()
+        pid = window.get_full_property(self._atom("_NET_WM_PID"), X.AnyPropertyType)
+        return WindowInfo(
+            id=hex(window_id),
+            title=title or window.get_wm_name() or "",
+            app=wm_class[1] if wm_class else "unknown",
+            pid=int(pid.value[0]) if pid else None,
+            focused=focused,
+        )
+
+    def _root_property(self, name: str) -> list[int]:
+        prop = self._root.get_full_property(self._atom(name), X.AnyPropertyType)
+        return list(prop.value) if prop else []
+
+    def _atom(self, name: str) -> int:
+        # get_atom caches, unlike intern_atom which asks the X server every time
+        return self._display.get_atom(name)
+
+
+class WaylandPlatform(LinuxPlatform):
+    """
+    wayland doesn't let clients inspect or control each other's windows, so this
+    backend relies on compositor utilities and can't list or focus windows
+    """
+
+    def grab_screens(self) -> list[Image.Image]:
+        self._require("grim", "screen capture on wayland needs `grim` (wlroots compositors)")
+        return [Image.open(io.BytesIO(self._run("grim", "-t", "png", "-")))]
+
+    def list_windows(self) -> list[WindowInfo]:
+        raise PlatformError("listing windows isn't supported on wayland yet; rely on screenshots")
+
+    def focus_window(self, window_id: str) -> None:
+        raise PlatformError("focusing a specific window isn't supported on wayland")
+
+    def send_close_tab_shortcut(self) -> None:
+        if shutil.which("wtype"):
+            self._run("wtype", "-M", "ctrl", "w", "-m", "ctrl")
+        elif shutil.which("ydotool"):
+            # linux input event codes: 29 = left ctrl, 17 = w
+            self._run("ydotool", "key", "29:1", "17:1", "17:0", "29:0")
+        else:
+            raise PlatformError("sending keystrokes on wayland needs `wtype` or `ydotool`")

focus_now-0.1.0/src/focus/tools/platform/macos.py

@@ -0,0 +1,14 @@
+from focus.tools.platform.base import UnsupportedPlatform
+
+
+class MacOSPlatform(UnsupportedPlatform):
+    """
+    TODO: implement on top of the shared Platform base.
+      - grab_screens: mss works on macOS (needs Screen Recording permission)
+      - list_windows / focus_window: Quartz CGWindowListCopyWindowInfo + AppleScript
+      - send_close_tab_shortcut: cmd+w via Quartz CGEvent
+      - notify: `osascript -e 'display notification ...'`
+    """
+
+    def __init__(self):
+        super().__init__("macOS")

focus_now-0.1.0/src/focus/tools/platform/windows.py

@@ -0,0 +1,14 @@
+from focus.tools.platform.base import UnsupportedPlatform
+
+
+class WindowsPlatform(UnsupportedPlatform):
+    """
+    TODO: implement on top of the shared Platform base.
+      - grab_screens: mss works on Windows
+      - list_windows / focus_window: EnumWindows + SetForegroundWindow (pywin32 / ctypes)
+      - send_close_tab_shortcut: ctrl+w via SendInput
+      - notify: toast notifications (e.g. windows-toasts)
+    """
+
+    def __init__(self):
+        super().__init__("Windows")

focus_now-0.1.0/src/focus/utils/log.py

@@ -0,0 +1,15 @@
+import typer
+from rich import print
+
+
+def err(message: str):
+    print(f"[bold red]error[/bold red]: {message}")
+    raise typer.Exit()
+
+
+def warn(message: str):
+    print(f"[yellow]warning[/yellow]: {message}")
+
+
+def log(message: str):
+    print(f"[green]log[/green]: {message}")

focus_now-0.1.0/src/focus/utils/prompts.py

@@ -0,0 +1,68 @@
+default_task = """
+
+You are "Focus", the most optimal focus solution available today, designed to help your users stay in focus and complete productive work while minimizing distractions and interruptions.
+
+Currently, your user has not specified a task to complete yet, so your job is to monitor the user and make sure they are doing "productive" work. 
+
+Examples of "productive" work include reading, writing, mathematics, homework, coding, video creation, and anything in general that "creates" and benefits your user in some way.
+
+Examples of "unproductive" work include scrolling X, Reddit, using Discord (for unproductive tasks / checking messages / scrolling for no reason), etc.
+
+You were created because current focus solutions are inadequate and fail to categorize "unproductive" from "productive" work accurately, instead relying on metrics like domain names. What they lack is the ability to discern whether productive work happens on unproductive apps or vice versa. Because of this, even if you suspect the user is being unproductive, wait for at minimum a couple seconds before deciding.
+
+Your core capability is to monitor the screen -- make sure the user is being productive.
+
+You have several tools available to you to minimize unproductive work. This includes the ability to remove tabs, notify the user through system notifications, and kill/exit apps.
+"""
+
+custom_task = """
+
+You are "Focus", the most optimal focus solution available today, designed to help your users stay in focus and complete productive work while minimizing distractions and interruptions.
+
+For this session, your user has told you exactly what they want to get done:
+
+<task>
+{task}
+</task>
+
+Your job is to monitor the user and make sure they are working on this task. Judge activity against the task, not against generic ideas of productivity: if the task involves watching a lecture on YouTube or researching on Reddit, those are on task; reading an unrelated article or coding on a different project is not, even though it would normally look "productive". Short, task-adjacent detours (looking up documentation, checking a reference, a quick message to a collaborator about the task) are fine.
+
+You were created because current focus solutions are inadequate and fail to categorize "unproductive" from "productive" work accurately, instead relying on metrics like domain names. What they lack is the ability to discern whether productive work happens on unproductive apps or vice versa. Because of this, even if you suspect the user is off task, wait for at minimum a couple seconds before deciding.
+
+Your core capability is to monitor the screen -- make sure the user is working on their task.
+
+You have several tools available to you to minimize off-task work. This includes the ability to remove tabs, notify the user through system notifications, and kill/exit apps.
+"""
+
+operating_instructions = """
+
+<how_you_operate>
+You run in the background for the whole session. Every so often you get a check-in message; each check-in is a fresh look at the user's screen. A check-in already includes a screenshot, so you don't need to capture the screen before deciding whether anything looks off.
+
+On each check-in:
+1. Look at the screenshot and decide whether the user is on task. Use list_windows when the screenshot alone is ambiguous (for example, to read a browser tab's title).
+2. If they're on task, do nothing and end the check-in.
+3. If something looks off, don't act on a single glance. Use wait for a few seconds, then capture_screen again. People glance at messages and look things up; only a sustained pattern counts as distraction.
+4. If the distraction is confirmed, intervene with the lightest action that will work, and escalate only when lighter actions have already failed in earlier check-ins:
+   - notify_user with a short, specific, friendly nudge.
+   - close_tab when a distracting tab keeps coming back after a nudge.
+   - kill_app only for repeated distraction in an app that has nothing to do with the task, after the user has been warned.
+5. After any close_tab or kill_app, capture_screen to confirm it did what you intended and didn't hit something the user needs.
+
+Never close or kill anything the user plausibly needs for their task, such as their editor, terminal, documents, or reference material. When unsure, prefer a notification over a destructive action. Losing the user's work is far worse than letting a distraction run a little longer.
+
+End every check-in with a single short line describing what you saw and what you did (for example: "On task: editing focus/agent.py in VS Code." or "YouTube gaming video for ~30s; sent a nudge."). These lines are your memory between check-ins, so make them useful to your future self.
+</how_you_operate>
+"""
+
+check_in = """Check-in at {time} ({elapsed} into the session).
+
+Your notes from recent check-ins, oldest first:
+{notes}
+
+Here is the current screen."""
+
+
+def build_system_prompt(task: str | None = None) -> str:
+    base = default_task if task is None else custom_task.format(task=task)
+    return base.strip() + "\n" + operating_instructions